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The world is a very different place since the last time you saw 
a MacTech, It’s different for all of us... Americans, Europeans, 
Asians... kids, grandparents, adults... those who are religious, 
and those who are not. The world is very different for everyone, 
everywiiere. 

Now is the time for us to take the tragedy of September 
Tith, and work relentlessly to create whatever good we can 
from this evil. In part, this means tliat we use this juncture in 
mankind’s history to take world unification to the next level — 
and learn to live and work l>etter with one another. 

In addition, many of die leaders around die world are 
urging that people return to their level of effons before the 
attack. They this hef''.4iise one* nf the best things that free 
people can do in the face of terrorism is not let it win, slow us 


down, or stop us. This means driving forward widi our projects, 
our plans, our industry and our economy. I strongly encourage 
you to do the same... as we are here. 

While stated millions of times at this point.,, and cannot be 
understated... our hearts, thoughts and prayers go out to those 
who lost dieir lives, or loved ones on that horrific day. 

There have been many ‘"moments of silence” as of late. 
WeVe going to take a moment now, and do the ""prinr version 
of this. Tlie balance of this page will remain blank in memory 
of those that lost their lives, those who selflessly leapt at the 
chance to save others, and for all those grieving their losses. 

Neil Tkktin, Publisher 
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By Spec Bowers 


The Under-used UserPane 


Presenting a Whole Slew of Nifty 
Controls 

IlNTRODlfCnOlN 

Could you use a QuickTime control, an MLTE control, an 
HTML Renderer control, a StoneTable control, a WASTE 
control, a Color Picker control? They’re all here - made out 
of a UserPane. 

Of all the controls Apple has created in recent years, the 
most llexible is tlie UserPane. It is also the hardest to use. Most 
of us probably just write spedal-purpose code in our update 
handlers or mouse-down liandlers rather than hotlier with the 
intricacies t)f a UserPane. 

With a simple wrapper class, the UserPane is very easy to 
use - and it makes other packages easier to use. We have made 
UserPane controls for QuickTime, MLTE. HTMI. Rendering, the 
Color Picker, the StoneTable list manager replacement, and the 
WASTE text engine. These packages are easier to use thanks to 
the UserPane. 



Figure h Four kinds of I her Pane 

Wrapping a UserPane control around QuickTime, MLTE, or 
other packages makes the code easy to reuse and greatly 
simplifies your event handling code. The QuickTime control is 


almost as simple as a standard pushbutton; the M1.TE control is 
easier tlian TextEdit. 

Your event loop already ha,s code for HandleControlClick, 
HandleCc >ntit>lKey, SetKeyboardFocms, Activate/DeactivateControl, 
Hide/ShowControl, and IdleControls. When you wrap a UserPane 
control around a package like QuickTime, it automatically responds 
to your existing control handling code. You can put controls for 
QuickTime, MLTE, HTMl. Rendering, etc. in a window^, a dialog, 
inside a tab panel - anywhere you put a standard control - and it 
just works. 

This article: 

• describes the functions of u UserPane; 

• presents a C++ wrapper class that makes it easy to 
use a UserPane; 

• presents several examples of UserPanes; 

• shows how to handle a UserPane in a window or 
dialog 

UskrPaime FuESicnoNS 

Apple defines several callback functions for a UserPane controL 

• A DrawProc draws the content of your controL It might be 
called to draw a part of the control but usually draws the 
entire controL 

• A HitTestProc returns the part code of the control where the 
moitse-down occurred. We usually just detect a mouse-down 
anywhere in the control and return a partcode which 
represents the entire control. 

• A TrackingProc tracks a control while the user holds down the 

mouse burton. 

• An IdleProc performs idle processing. 

• A KeyDownProc handles keyboard events. 

• An ActivateProc liandles activate and deactivate events. 

• A FocusProc handies keyboard focus - e.g. for 
Set/Ad va nceKey I ')oardFoc u s . 

• A BackgroundProc sets the I background color or pattern for 
embedded controls. 


Spec Bowers is the founder, cook, and diief bottle washer at Bowers Development. He has been developing programming tools for most of hi.s career. 
You can contact him at bowersdev@aol.com or see the web page at http://members.aoLcom/bowersdev 
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To install a callback you first create a XJPP, then pass it to 
the control via SetControlData. Later, to prevent a memory leak, 
you should dispose the UPR Alternatively, you can adopt a 
“create once and reuse” protocoL Whatever way you do it, 
installing a callback is a nuisance- The AMUserPane makes it 
very simple to install a caUback. 


The AMUserPane Class 

The AMUserPane class provides functions for easily 
installing callbacks and for disposing of UPPs when the control 
is discarded, provides some standard callback functions, and 
provides some utility functions to simplify using a UserPane. 

To Install n DravProc* just call "SetDrawProc 0": 


n - 

void AMUserPane: ■ SetDrawProc () 

[ 

mDrawUPP “ NewControlUserPaneDrawUPP (StaticDrawProc); 
: jSetGontrolEiata (mControli 
kControlNoPart. 
kControlUserPan&DrawProcTag, 
size of (jnUrawUPP) ♦ 

(Ptr)6(inDrawUPP ): 


} 

There are slfflilar functions for installing a TracklngProc* 
KeyDownProc, ActivateProc» etc. 

AMUserPane declares data members for each callback function: 


ControlUserPaneDraTtfUPP 
Contr 0 1Use r Pan eHit Tes t UP P 
C 0 nt ro 1 Ua e r Pan eTra ckin gUP P 
C ont r01Ue e rPaneIdleU P P 
C ontr D1 Us e r Pan eKe y D ownlJP P 
Cont r 0 1Us e rPa n eAc tivateUP P 
ControlUserPanePocusUPF 
ControlUserPanePackgroundUPP 


mDrawUPP: 
iiiHitTestUPP: 
JoTracklngUPP; 
mldleUPP; 
inKeyDownUPP; 
mActivateUPP: 
mPocusUFP: 
mBackgroundUPP; 


Its constructor initializes each UPP to nil* and its 



Fetch 4.0 


destructor disposes each (non-nil) UPP: 

If— 


AMUserPane::AMUserPane C) 


E 


njDrawUPP = nil: 
mHltTestUPP = nil; 
mTrackingUPP = nil; 
mldleUPP - nil: 
mKeyDownUPP nil: 
mActivateUPP = nil; 
mPocusUPP * nil: 
mBackgroundUPP = nil; 


//- 

AMUserPane:AMUserPane () 

I 

if (mDrawUPP 1= nil) I 

DlsposeControlUserPaneUrawtrPP (mUrawUPP): 

1 

if (raHitTesttlFP I- nil) t 

QisposeControlUserPaneHitTestUPP (mHltTestUPP): 

) 

if (pTrackingUPP 1^ nil) ( 

UisposeControlUserPaneTrackingUPP (mTrackingUPP): 

I 

If (inTdleUPP 1= rdl) { 

DiaposeControlUserPaneldleUPP (tnldleUPP) : 

1 

if (mKeyDownUPP 1= nil) { 

DisposeControlUserPaneKeyDovnUPP (raKeyDo-wnUPP): 

! 

if (mActivateUPP E= nil) [ 

DisposeControlUserPaneActivateUPP (mActivateUPP): 

1 

if CmFocusUPP !" nil) [ 

DlsposeControlUserPaneFocusUPP (mFocuaUPP); 

I 

if (mBackgroundUPP 1“ nil) { 

DisposeControlUaerPaneBackgroundUPP {mBackgroundUPP); 

I 
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Look back at SetDrawProc and you’ll see that it installs a callback 
to a function named "^StaticDrawProc”, AMUserPane provides a 
member function, DoDraw, which Ls overridden in each subclass. 
The StaticDrawProc is a glue function which dispatches to the 
particTjlar DoDraw of the subclass - the QuickTime DoDraw^ or 
the MLTE DoDraw, for example. During initiali2:ation we store a 
pointer to a specific instance of AMUserPane in the control's 
RefCon. In each callback we retrieve the controLs RefCon, cast it 
to an AMUserPane pointer, then call the member function. 

a - 

void AMUserPane; :Initiali 2 ’e ( 

ControlHandle inControU 

t 

mControl = inControl: 

: iSetControlReference (niGontrol, (SIiit32)this): 


// - 

pascal void AMUserPane::EtaticDrauProc [ 

ControlHandle control. 

SIntl6 part] 

f 

AMUserPane* pane = (AMUserPane''GetControlReference 
[control]: 

pane-)DoDrav (part); 

f 

// - 

void AMUserPane: iDoUraw ( 

SIntl6 part] 

I 

// override In each subclass 

1 

AMUserPane is a base class; ii provides common code Ibr a 
wide variety of IJserPane eontrols. We have made half a dozen 
subclasses. Lefs take a look at some of iheni. 

A ColorSwatch DserPane 

Our simplest LIserPane is a wrapper around the Color 
Picker. It paints the control’s rectangle with a color. If tlie user 
clicks the DserPane, it invokes the Ct)lor Picker, dien redraws 
tlie rectangle with the selected color. We overrode DoDraw' and 
DoTracking. The Initialize function calls SetDraw'Proc and 

SetTrackingProc to install callliacks. 

// - 

void AMColorSwatch ; iCoDraw ( 

SIntl6 /* part */ ) 

] 

RGBCoIcr saveColor: 

Rett rsct; 

:;GetForeColor C&saveColor): 

: : RGBForeCoIor {^mSwatcliCoior] ; 

GetControlRect (&rect]: 

::FaintRect (Srect): 

: iRGEPoreColor: (^saveCoiorj ; 


//- 

ControlPattCode AMColorSwatch;iDoTracking ( 
Point startPtn 

ControlActionUPPactionProc) 

I 

ControlPartCode result = 0: 

Point dialogPos = (0, 0); 

Str255 proTupt = "\p"': 

RGBC olo r out Color; 


if (::GetColor (dialogPos, prompt, fiimSwatchColor, 
&outColor)) f 

mSwatchColor - outColor; 

DoEraw (O); 

result =95; // any non-zero code 

I 

return result; 

] 

//- 

void AMColorSwatch::Initialise ( 

ControlHandle inControl) 
i 

AMUserPane:;Initialize (InControl): 

SetDrawProc [); 

SetTrackingProc (): 

[ 


An HTML Pane - GuTcms and Solutions 

The HTML pane is only slightly more complex but illustrates 
two glitches. The first time we put it inside a Tab control it worked 
pretty well Clicking a tab results in HideConirol/SliowControl of 
the panels. Each panel is a simple DserPane with eml^edded 
controls. When we hide or show a panel, the Control Manager 
hides or shows any embedded controls, including our custom 
UserPane controls. (Tliis by the way Ls one of the advantages of 
turning QuickTime, MLTE, etc. into UserPane controls -- 
HideControl, ShowControl and other Control Manager functions 
work the sjtme as with standard controls.) 

Iliere was a glitch, though. When we deactivated the window, 
suddenly one of our hidden DserPane eontrols drew someiliing. 
Ilie Control Manager doesn’t call tlie DrawProc of a hidden control 
but it may call die ActivateProc. We added a simple “IsVisible" call 
to test Ibr visibility inside any of our callback fiinclions that might 
draw anything. 

// - 

void AMflTMLPane:: DpActlvate ( 

Boolean activating) 
i 

Rett cntlKect; 

if (IsVisible {)) \ 

if (activating) 1 

HRActivate (mHTMLRec)[ 

I else I 

HRDaactivate (mHTMLRec); 

] 

1 

I 

Til is didn't coiTiplerely solve the problem, however. We saw 
the HTV'Tl.Pane’s scrollbars even when the pane was hidden. This 
w'as beatuse the scrollbars were not properly emlx'cJded witliin die 
LUML DserPane. The HU ML Rendeiitig Lib creates scrollbars on the 
fly its needed. Uiose scrollbars end up embedded in the rocA 
control. Because tliey are not embedded in tlie HTML U.serPane 
they are not liidden/shown along witli die pane. Our solution Ls to 
look for newly created controls in the root control and embed them 
in our UserPane control. 
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Before we call any function that might create other controls we 
call CountRootControls. Afterwards, we c'all EmbedNewControls. If 
there are more controls afterwards than before, those new controls 
should be eml:)edded in our UserPane, not in the KX)t control 

//—- 

UIntl6 AMUserFane; iCountRootContr'Qls () 

I 

Ulntlfi ntuneontrols - 0: 

WlndowRef theWindow: 

GontrolRef root; 

theWindov = GetOwnerWindow {]: 

:: Get Root Control {tbeWindow. firoot) ; 

:: Count Sub Controls (root, &nuiiiControIs) ; 

return numControls; 

) 

// - 

void AMUserPane: ;EniliedNewC on trots ( 

Glut16 inBeforeNum) 

1 

WindowRef theWindow: 

ControlKef root; 

Ulntlfi afterNutn; 

Ulntlfi i: 

GontrolRef ohild: 

theWindow = GetOwnerWindow (): 

::GetRootControl [theWindow, fiiroot); 

;:CountSubControls [root, ^afterMum): 
for [i = afterNum; 1 > inBeforeMuin; i—) [ 

;:GetIndexedSubGontrol (root, i* Schild): 

: :EinbetiControl (child, mControl} ; 

I 

] 

In most of our llserPanes' lnitiali;^:e functions we call 
CountNewContrals and Eml^edNewControls just in case sul3a:)nlrols 
are treated, llie Hl'MLFane's Initialize Ls typical We get a 'Before’’ 
count of root controls, create a new HRReference, then set its 
[founds to the UserPane contmls Ixninds. We install a DrawProc, 
TrackingPrtx:, and ActiwiteProc. Fmaily, we embed the newly 
created cc^nlroJs (scrolllrars) in Be UserPtme. 

//- 

void AHHTMLPanet:Initialize ( 

GontrolHandle inContral) 

\ 

AMUserPaneInitialize [inControl): 

OSErr err = noErt; 

Ulntlfi beforeHuju: 

Rect cntlRect: 

GrafPtr ownerPort: 

beforeNum = CountRootControls C); 

GetControlRect (fiscntlRect): 

ownerPort = (GrafPtr) GetWindowPort (GetOwnerWindow ()); 
err = HRNewReference {SimHTMLRec, kHRRenderei:HrMtJ2Type. 
ownerPort): 

If (err = noErr) I 

HRSetRenderingRect (tnHTMLRec, SccntlRect): 

HRSetDrawBorder (mtiTMLRec.^ true) : 

SetDrawProc (); 

SetTrackingProc {): 

SetAdtlvateProc (): 

i 

EmbedNewControls (beforeNum): 

f 

Hie HTMLPane was now working well - until we viewed an 
HTML file tliat had a frameset. Suddenly, there were two new 


scrollbars and tliey were not embedded properly. So we added 
CountRootControls and EmbedNewControls to the DoDraw 

function. Other than that, the DoDraw is very simple. 

// - 

void AMHTHLFane::DoDraw { 

Slntlfi part) 

[ 

Ulntlfi beforeNum; 

Rect cntlRecit; 

beforeNum - CountRootControls 0: 

GetControlRect (icntlRect); 

HRSetRenderingRect (niHTMLRec, totiRect): 

RectRgn (mHTtMgri, ^ontlRect). 

HRDraw (mHTMLRec, caHTKLRgn}; 

EmbedKewControla (beforeNum}; 

// in case last click created new scroll bars 

I 

The DoTracking ftmction is very simple. About all it does is ask 
the HTML Rendering library to handle the event We could have 
synthesized a mousenjown event from the Start Point but instead 
we call an external function to get tlie current event record from our 
main event-liandling code. 

//—- 

ControlPartCode AMHTMLPane::DoTracking ( 

Point startFt, 

ControlActionUFP actionProc) 

I 

WindowRef owner = GetOwnerWindow (): 

::SetPortWlndowFort (owner); 

::HRlsHREvant (GetCurrantEventRecord (}): 

return 99; // any non-zero code 

[ 


Using a UserPane 

Okay, so we have written a UserPane elass. 1 low do we use 
it? That's the easy part. First, create a UserPane control resource. 
For a window or a dialog, create a CNTL with procID 256 and 
initial value 318. This value turns on feature bits for 
Supports Embedding, SupportsFocus, Want sidle, WantsActivate, 
Handle,sTracking, and GelsFocaisOnClick. For a diakjg, in its 
Dm resource create an item of type Coniroi and set its ID to 
the resource ID of the CNTI. resource. 

Wherever you declare the variables (data memliers) hr your 
window or dialog, declare an instance of the UserPane class. We find 
it convenient also to declare a GontrolHandle. You1l also have to 
^idude the UserPane da^ss’s header. 

^include ""AMColorSwatch.h" 

ControlRandle uiSwatchHandle; 

AMColorSwatch mSwatchPane; 

When you create a window, get a CoiitioUdandle to the 
UserPane control, then initialize the instance of the UserPane class, 

mSwatchHaiidle = ::GetNewGontrol [CNTL_Swatch. window); 

mSwatchPane.Initialize (mSwatchHandle); 

In your window's event handling code for a moust^-down, call 
the usual FindControl If the click is in the UserPane control, call the 
usual TrackControl or HandleControlClick. 

if (whicbControl = mSwatchHandle) I 
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if {HandleControiClick tmSwatchHandle, where. 
curEvent.modifiers* nil) 1“ 0) t 
1 

1 else if (mSwatchPane.ClickSubControl (whichControl, 
where)) I 

// ClickedSwatch (): 

I 

Whai is “ChckSubContror? If the UserPane has any 
subcontrols, e.g. scrollbars, then FindControl may find that the 
click was in the scrollbar. ClickSubControi checks to see if the 
click was in one of the UserPane^s subconirols. If it was^ then 
ClickSubControi passes the click along to the UserPane class's 
DoTracking metliod and returns true. If the click was not in a 
subconlrol, then ClickSubControi returns false. 


//- 

Boolean AMUserPane::ClickSubControi 
ControlRef inControl, 

Point InWhere) 

f 


UlntlS nuinSubs; 

Ulntlb i: 

ControlRef sub: 


( 


:iCountSubControls (mControl. &numSubs); 
for (i = 1: 1 <= numSubs: i++) I 

r iCetlndexedSubControl fmControl* i. Saub); 
If (inControl = sub) f 
DoTracking (inWhere * nil): 

U treat it as a click in the userFane 
return true: 

) 

I 

return false: 
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necect stale handles, runtime block overwrites, 
DlsposeHandle on resources, invalid BloclcMoves, 
writes to location zero. Validate Handle/Pointer 


The example application doesn't have any UserPanes in a 
dialog but ifs eas>^ to do. After aeating the dialog, call 
GetDialogitemAsControl to get a ControlHandle to the UserPane. 
Then Initialize the UserPane instance with the control handle. The 
Control Manager and Dialog Manager will take c^ie of almost 
everything. You just add a case to your dialog's switch statement, 
Tliere is one other piece of code you will have tc} add if your 
UserPane has subcontrols. You’ll have to add a Filter function 
because the Dialog Manager doesn't know anything about tlie 
subcontrols. The Filter function will liave code like this: 

if (in£JuickTiinePane.FllterSubCk)iitrDlfi (loEvent)) 1 
“outltemHit = kQuickTimePane: 
return true: 

1 

FilterSubControls checks to see if the event is a mousendown. 
If it is, then FLlteiSubContiob calls FindWindow and FindControl, 
then calls CUckSubConUol, which we saw earlien 

U - 

//if the event is for one of our subcontrols 
if then process it as if it were for us: 

// pass back true to tell Dialog tannager 
// that event has been processed 
// 

Boolean AHUserPane::FilterSubControls ( 

EventRecord *ioEvent) 

f 

Boolean filtered “ false: 

UlntlS numControls = 0: 

WindowPtr whichWindow; 

ControlHandle whichControl: 

Point local Where; 

short partCode: 

UIntl6 i: 

ControlRef sub; 

::CountSubControls (ntControl* SnumControls): 
if (numControls > 0) ( 

if ((ioEvent‘>iidiat “ mouaeDown) 

kk (FindWindov (loEvent->where, iwhichWindow) ^ inContent)) 

I 

SatPortWindowPort (whichWindow); 
localWhere = ioEvent->whGre: 

ClobalToLocal (ilocalWhera); 

FindControl (localWhere, whichWindow. ^whichControl): 
if (ClickSubControi (whichControl. localWhere)) f 
return true: 

// ^> click was for this userPane 

1 


I 

return filtered; 


Summary 

WeVe described two of our UserPanes - the Color Picker and 
the ITl'ML Renderer. The other four UserPanes - for QuickTime, 
MLTE, SioneTable, and WASTE -- are similar. The AMUserPane class, 
all six UserPane classes, and tiie example application are available 
as source code. Hie controls are useful and easy to use. If you use 
any of them we would be interested in hearing from you. 

APlug 

These UserPane classes are part of die AppMaker library. The 
example was created using AppMaker, which generated both the 
resources and the source ctxle, Wlietlier you use AppMaker or you 
do it by hand, 1 think you will find that these UserPanes are very 
useful widgets to liave in your ttxillTOx. K1 
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BEGIIUMiniG 
WEBOBJECTS 5 


By Emmanuel Proulx 


Part 1 - Presenting WebObjects 5 


Introduction & Installation 


Preface 

This new column deals with WebObjects 5. It is meant 
to be easy and fun to read. This column talks about 
developing a Web application using WebObjects 5, in 
Java. Originally, this column was a book, with hundreds 
of pages. It has been cut down a lot to accommodate 
space restrictions. 

Those interested in learning to build Web applications 
using WebObjects 5 should read this column* The only 
prerequisite is being Java programmers of at least 
intermediate level 

Other knowledge is not necessary, although 
understanding HTML ha.sics can help tremendously 
because WebObjects borrows many characteristics From 
this language. If you don't know HTML at all but you still 
want to learn WebObjects, just skip the paragraphs that 
talk about HTML. For your convenience, these are usually 
marked with the symbol <HTML>, You won’t get into any 
trouble, but you will not understand how WebObjects 
works behind the scene. 

The same thing goes with databases. While knowing 
databases and SQL isn’t necessary, you have to have basic 
knowledge if you’re going to read the sections about 
databases. Database software is necessary if you’re going 
to try out WebObjects’ database features. I tried to keep 
all of the database interfacing and programming contents 
in separate sections for convenience. 

Note that someone who masters Java programming, 
client/server design, HTML and Web Design as well as 
databases and SQL will be able to learn WebObjects 
radically faster. 

What Is WebObjects? 

I started this new job and the job description was 
“Java Developer”. 1 was expecting to use one of these 


Java IDEs like Visual Cafe or Visual Age. My new boss 
said, *‘No, here we use WebObjects". I had heard about 
that tool, but 1 didn’t know it was a Java IDE, It wasn't. 

WebObjects is an environment for developing 
interactive Web Sites. The Java language is being u.sed to 
implement Server-side behavior; the client side is mostly 
HTML, not nece.ssarily Java Applets or even JavaScript for 
that matter, 

WebObjects is much more than that. If also falls into 
the Application Server category. What is that? In the past, 
a “Server” would consist of just a Database. Nowadays a 
Server can also handle distributed transactions, multi-tier 
architecture, load-balancing, business logic, Enterprise 
JavaBeans, and other concepts and technologies involving 
more advanced server-side intelligence. An environment 
that helps with the development and deployment of such 
complex Servers is called an Application Server. 

WO consists of multiple tools that are tightly 
integrated. 

• Project Builder: lets you browse the .source code and 
manage the project. 

• WebObjects Builder: lets you assemble a Web Page. 

• Enterprise Object Modeler: let.s you connect your 
Web Application to a database, 

• Interface Builder: lets you create Java applications 
and applets that connect to the WebObjects server for 
executing business logic and database access. 

• Direct To Web: a wizard that create.s a complete 
database-driven customizable Web application. 

• Direct To Java Client: a wizard that creates a 
complete database-driven customizable Java program 
or applet. 

• Monitor: a remote task monitoring and performance 
analysis utility. 

Other smaller utilities like a 'DifF utility, debugging tools, etc. 


Emmanuel Proulx is a Q>uise Writer, Author and Web Developer, working in the domain of Java Application Servers. He can be reached at 
emmanuelp® thegl obe .com. 
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Other modules are included, yet they are not visible: 

• Web Setter Adaptor: plugs into your Web Server to 
connect it to Web Objects. 

• JDBC Database Adaptor; connects WebObjects to a 
database driver. 

• The frameworks, which are powerful programming 
libraries. They support the whole WebObjects system. 
We refer to them as the Foundation, WebObjects and 
Enterprise Object Frameworks, The preceding tools 
make use of the Frameworks, and even generate some 
code that uses them. 

flow do these tools work with each other? Tfie 

Figure 1 illustrates their interactions. 



tAfebObjects Builcfer 

Figure 1. Interactions between the tools 

In a typical WebObjects application, the focus is the 
project file, which points to the different components of 
the application. The Project Builder manages this file. 
Then, to create the Web Components (Web pages), you 
usualiy run the WebObjects Builder program. When a 
component makes use of a database, you have to use a 
model to link the tables of the database to your system's 
objects. This model is created using the EO Modeler. To 
let a user connect to your site, you need a Web Server 
containing the WebObjects Adaptor. There's more on each 
of these parts later on. 

Lastly, WebObjects also is an IDE for developing 
Cocoa and Carbon applications, hut this column deals 
only with Web applications. 

Installation Information 

First you must know that there are two distinct 
packages that can be installed with WebObjects 5. Each 
has its own specific use and list of installed components. 


• Developer edition: Contains all the graphical tools 
and libraries. Used for the development environment. 
At the time this was written, only the Mac OS X would 
support the Developer Edition. 

• Deployment edition: contains only the deployment 
tools and the run-time libraries. Used for the 
deployment environment. Can be installed on top of 
the Developer edition on Mac OS X. The Deployment 
Edition is available for a variety of platforms. 

This column generally talks about the Developer 
edition. The Deployment edition will be covered in a 
separate article. 

To develop with WebObjects Developer Edition, you 
need a Mac OS X environment with at least 128 megabytes 
of RAM and 600 megabytes of hard disk space. That said, 
remember this golden rule: you never have enough RAM 
and hard disk space! 

Once youTe done with your developmeni, you can 
deploy your application on either Mac OS X, Windows 
2000, or Solaris. 

You will also need a supported Web server On the 
Mac OS X, the default server is Apache, and works great. 

If speed doesn’t matter that much to you, you can get 
any Web Server with CGI capability. Else, you have to get 
a Web Server compatible with either the NSAPl or WAI 
.standards (Netscape’s Web Servers), IS API (Microsoft’s 
Web Servers) or Apache. Of course, select a Web Server 
that works on your deployment platform. 

If you need to access a database, you want to use one 
that has a JDBC 2,0 driver. WebObjects comes bundled 
w ith an evaluation version of O pen Base. But on 
deployment platforms you may want to go for an 
industrial-strength database, like Oracle, Informix, Sybase, 
DB/2, etc. You can also connect to any ODBC-compliant 
clatabase on Window.s using the ODBC/JDBC bridge, but 
that would make things .slower. 

NOTE: Not many database products are available on 
Mac OS X, so you may want to purchase a complete 
version of Open Base (www.openbase.com). 

Installation 
Pre-Installation Steps 

It is very important to install your Web Server before 
you install WebObjects. 

NOTE: if you already installed WebObjects and you 
want to install a Web Server afterward, the only issue is 
with the “cgi-bin" folder. WebObjects has already copied 
its required executables in a temporary "cgi-bin” folder 
After setting up your Web Server, you wdll have to copy 
these executables in the new Web Server’s '‘cgi-bin” folder 
(you will have to make one if there is none). 
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Also, it doesn’t hurt to install your database software 
at this point if you don’t have one already. 

On Mac OS X, both Apache and OpenBase are 
installed by default. 

To install WebObjects on any platform, you need to log 
on as the Administrator (or root) user. If you don’t have 
Administrator (or root) access rights, it won’t work at all. 

On Mac OS X, you have to first enable the root user 
(which is blocked by default) and then to log on as the 
root user. To enable the root user, open folder 
/Applications/Utiiities, and double-click on Netinfo 
Manager. Once Netinfo Manager is running, open menu 
Domain | Security | Enable Root User. You will be asked 
to enter a password for the root user. Now log off and log 
on again using Toot’ as the user name, and tlie password 
you set previously. You are now lagged as the root user and 
ready to install. After the installation is finished, you may 
disable the root user by running Netinfo Manager again. 

Installation Steps 

Insert your WebObjects CD in your CD-ROM drive. 
Double-click on the new icon that shows up in the 
de.sktop. Now double-click on the icon marked 
WebObjects_X_Developer,mpkg. This will call the 
installation program. Then, follow the instructions in the 
wizard-like window. 
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The following notes are meant to help you along the 
way. Read them before staning the install: 

• The serial number is usually located on a sticker on 
the CD envelope. 

• Be sure to read carefully the License Agreement for the 
next two hours. ;-) 

• Most people should choose a Typical Install. The 
Typical Install includes everything except the 
following (generally unimportant) items: 

• The Japanese language support 

• The source code 

• At one point, the WebObjects installation program 
could ask you for your Web Server’s “cgi-bin’’ folder 
and its “docs” folder. Check them out and write them 
down before you start the install. 

• This process takes a very long time - be patient. 

• You will need to restart your computer at the end of 
the install, so it’s a good idea to save your data and 
close all programs before even starting it. 

Patches 

I recommend that you install the latest patches for all 
of these (if you use them): 

• WebObjects itself 

• The operating system 

• The Web server 

• Your database software 

For the Mac OS X, updating to the laiesi patch Is very 
easy. You can get all the patches by going to the System 
Preferences panel, in the category Software Update. You 
will find there a button “Update Now’\ Clicking on It will 
check all software versions against an online database of 
patches. It will propose updates when they are available. 
J suggest you apply all of them. At the time this article 
was written, there was one patch available, which fixes 
many bugs. Install it. 

On other platforms, updating to the latest patch may 
require that you visit each vendor’s Web site and check 
for patches there. That’s it — you are now ready to enjoy 
your development environment. 

I didn’t cover the deployment installation here 
because it is a complex topic that deserves its own article. 

The Find-A-Luv example 

I designed this column to have a good balance of 
theory and examples. I took good care of the theory, but 
1 didn’t want to make tiny useless examples and toy-code 
I had seen too often. Also, I didn’t want to just show how 
to use the wizards of WebObjects and leave you alone 
with the customization. 1 needed a real Web Application 
and 1 wanted to develop it from scratch, not using just the 
wizards... 
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So throughout this column, I will be developing, as 
the main example, always the same Web Application. It 
features a Web Site for an imaginary dating services 
company. This company's promise is to help find nothing 
less than the client’s soul mate. But be forewarned: if 
you're looking for your soul mate, this column will not 
help you. 

We will start small and we'll expand this example as 
we go along. 

Web Development Alternatives 

WebObjects is not alone. There's a lot of competition 
out there. Many tools offer interactive Web Site/Server- 
side processing and Application Server solutions. Let's 
digest a few of the most popular ones. 

Competing Interactive Web Site Solutions 

The first ever solution for that is the CGI (common 
gateway interface). This is the most primitive solution. 
CGI is not a prodLici; it's a feature of your Web Server that 
lets you insert your own program in you Web Site, That 
program can receive the user’s input, and outputs a new 
Web Page based on it. The main disadvantage of the CGI 
is that the HTML code and database access are 
encapsulated into the source code; this is not pretty nor 
is it easy to develop. The main advantage is that you don't 
have to buy software to use CGI programs since it’s 
already in your Web Server. Just use any computer 
language and you're on your way. 

Sun Microsystems’ Java Servlets are based on the 
same idea as CGIs, except they are written in Java and use 
their own module (called Servlet Runner program) that 
adds on to the Web Server. They have similar advantages 
and disadvantages as CGIs except for the fact that certain 
Web Servers don’t support Servlets natively. Or if they do, 
their quality leaves a lot to be desired. This is the reason 
why commercial third party Servlet Runner programs (like 
Allaire's JRun) are available. 

Allaire's ColdFusion is a commercial product that lets 
you write HTML “templates”. That is, you write your HTML 
like you would normally do for your Web Page, and then 
you add in the same file the logic that makes the page 
interactive. You can even link your page to the database in 
only a few steps. The advantage is that you can use an 
HTML graphical editor for most of the work, and then add 
the logic afterward. ColdFusic^n is easy to use and produces 
results fast (just like HTML does). The main problem with 
ColdFusion is that it's not a real computer language; you 
can quickly arrive at the limit of what it can do. 

Microsoft’s ASP (Active Server Pages) also relies on 
“templates". But the logic is coded with Visual Basic, The 
main advantage is, like ColdFusion, fast development and 
tools that let you create pages easily. The disadvantage is 
that ASP is not portable: you can only use it on 
Microsoft’s Web Servers. 


Sun Microsystems' JSP (Java Server Pages) is an 
important playen JSP is based on the same idea as ASP, 
but the logic is coded in Java, 

Here’s a grid that summarises the different 
characteristics of these solutions: 
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Competing Application Servers 

When Sybase wanted to issue an application server, tiiey 
decided not to reinvent the wheel. They put together a set of 
existing tools then integrated them. Their Enterprise 
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Application Server Cor EAServer) is composed of Sybase’s 
Jaguar CTS (application server) and PowerDynamo (Web 
server). EAServer is integrated with development tools like 
PowerBuilder and Power], but these come separately, 
IBM’s application server is called simply WebSphere 
Application Server (Standard Edition). It features Servlets and 
JSF, a Web Server, and integration with Visual Age for Java 
and WebSphere Studio — sold separately. The Advanced and 
Enterprise editions offer more features, like EJB, better 
performance, security and other advanced features. 

The Oracle Application Server provides a basic set of 
features; Web Server (with Servlet and JSP support), EJB, 
a stable and sealeable environment for deploying Web 
applications. It is also integrated with Oracle's IDEs, 
Oracle Developer and JDevelopen 

BEA’s WehLogic Server is an application servers that 
follows the J2EE standard to the letter. It Features also 
Servlets and JSP for the dynamic HTML part, integrated 
with the most popular third-party IDEs. EJB, java 2 
Enterprise Edition and the latest standards are supported, 
Here's a grid that summarizes the different 
characteristics of these solutions: 
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As 1 am writing ihi.s book, there are countless 
different application server packages on the market. I will 
not cover them all, but I am convinced that only 
WebOb]ecti> covers such a wide variety of tools and 
features. But in general, I have noticed that most of the 
other application servers are just a bunch of distinct tools 
put together. Many of these products are tied to a single 
Web server or database. On the other hand, WebObjects 
has fully integrated tools that work together as a whole 
and leverages whatever tools (Web Server, database) you 
already have. Its programming libraries and database 
tools are jewels and no other vendor offers similar tools. 
While WebObjects does not follow the J2EE specification, 
its proprietary nature enables Apple to provide easy-to- 
use RAD tools and many 'Value-added'' features. 
Furthermore, WebObjects is the only application server 
available on the Mac OS X. MI 
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PROGRAMMING 

PHILOSOPHY 


By Marcelo Amarante Ferreira Gomes 


Mac vs. Unix traditions 


How to combine the best of both with 
MacOS X without gathering the worst 

A Big Move 

With the advent of Mac OS X, Apple has departed from the 
traditional Mac OS system software to a new model, that of Unix. 
Tills has brought a great impact, both upon users and 
developers. In this article, Fll concentrate on the impact it has on 
us, developers. 

Mac OS X brings a lot of changes. We now have a single 
filesystem tree, for instance, instead of a tree for each mounted 
volume; we have lots of users, instead of the few we had witli 
Classic, even though most are fake, like root or bin; we have a 
much more complex concept of process ownership, with 
process groups, effective and real user and group IDs and a 
controlling tty. Uiese - and lots of other - changes also change 
the way we code, something that even resembles the move from 
68k to PPC in 1994, but is a lot closer to the move from System 

6 to System 7 in the late 80's and early 90's* 

lliere were no new^ things to diink of when we moved from 
68k to PPG, only lots of programming pitfalls. But when System 

7 came up, later to be renamed Mac OS 7, we actually had to 
tliink different. Those readers old enough to remember will 
recall that when System 7 came up, we had to think of High- 
level events, mostly Apple evenLs, for simple tasks like opening 
a document, and try to use them whenever possible, instead of 
die low-level events and Finder lists we were used to. We had 
to revamp our user interface, so that our applications wouldn't 
look displaced in that new and way cooler-looking GUI. We had 
also to do away, once and for all, with our 24-bil stuff and use 
32-bit-clean pointers and handies, paying attention to the 
possibility of the use of virtual memory in the system. 

For those of you new to Macintosh, but experienced Unix 
developers, there were a few similar moves that the Unix 
community has gone through, too. They have been much 
smoother, since there was no single company dictating 
directions to developers, like Apple does in the Mac arena. To 


name a few, there was the move from the single mainframe with 
lots of terminals to lots of networked personal workstations; from 
IRJCP and serial-based WAN links to TCP/IP and Ethernet-based 
LANs; from character-based UI to X-based GUI; from single- 
computer passwd files to distributed NIS and/or shadow user 
databases. Some of these were actually additional options, rather 
than changes. For instance, 1 hardly recommend the use of NIS, 
even though I do recommend shadow password hies. And even 
today, 1 still recommend UUCP links and character-based UI in 
specific cases. But eidier the new features or the changes in them 
required some extra care in the way one writes a new piece of 
software, and fm not referring only to programming pitfalls here. 

1 could go on, naming other changes like these, both in the Mac 
and Unix fields, but the important thing here is to point out that there 
are some major moves in devekipment scenarios from time to time. 
And when such a move brings lots of changes at once, it also 
prcxluces changes in the programming philosophy. Tliafs what’s 
happening with the introduction of Mac OS X. And tliose of us who 
fail to perceive this will prohibly also fail to .survive in a market tliat 
is always hungry for state-of-tlie-art tedinology. 

What’s A Programming Philosophy, Anyway? 

It’s not only about programming caveats. The programming 
philosophy encompasses the way we design, we use, and even 
think about the uses for a computer system. Most Macintosh 
users think of their computers almost as a friend, while Unix 
users tend to tliink of tliem only as a tool to get some job done. 

Mac OS has traditionally been very user triendly and lilglily 
customizable but very consistent dirough different applicadons, 
lx)th in terms of the interface with die user and the functionality. 
Unix, wliile highly customizable in functionality - even more 
than the Mac in most aspeas ^ is usually very harsh with its fixed 
user interface. It seems to have been designed to work as a 
seiver, while the Mac OS is a great workstation. 

Veteran developers always lake these facts into account, 
even if unconsciously, and write code tliat corresponds to their 
perception of wh^l the user needs. What Apple is doing now 
widi Mac OS X is bringing the two worlds together, releasing an 
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OS lhat is great for both a server machine and a workstation. 
Tills means diat Apple wants users to have tlie same consistent 
user interface through all pieces of software they interact with, 
while having rock-solid system stability and compatibility. 

Give Users What They Need 

To build a successful Mac application, one must deliver 
what tile user needs. Note that this does not mean that you 
should code just what the user expects. You can and should 
surprise the user with new and improved ways to do 
something. But try to invent features that users would guess 
when presented with a given screen. Developers with no 
previous Mac programming experience should observe 
mainly the Mac human interface guidelines. The typical Mac 
users expect every application to be similar to all others. 
They are used to reading the manual only as a last resort. 
Applications should be intuitive to them. 

Apple has defined die recommended human interface 
guidelines required to achieve a successful Mac application long 
ago. These are constantly being improved, as new creative ways 
to interface with the users are developed, but the basic rules are 
always the same. What they say can be summarized as: 

• w^hen you add a feature to your software, do it in a way that 
resembles something you’ve seen before in another software; 

• if the feature you’re adding is radically new, try to imagine 
what the user would do to access that feature. Better yet, 
make a prototype of your application and have long-time 
Mac users play with it for some time. Pay attention to what 
they try to do, and listen to their comments very carefully. 

Tliere are lots of standard Mac OS interface elements that 
can be used to give users a clue to what they should do to get 
sometliing done. If your particular feature does not fit into any 
interface elements, you should probably talk to a veteran Mac 
user about it. If you both decide there's no interface element tliat 
fits your needs, then try to invent your new elemeni as similar 
as possible to another existing element. And always provide 
clear visual clues of the way your new element works. 

Be Compatible - And International 

In Mac OS, as well as in Unix, there are some conventions 
about where to put settings files, support code libraries, font files 
and lots of other things. Unlike in Unix, though, these special 
places should not be referred to by name. Apple has introduced 
the FindFolder system call a long while ago to give your software 
the path to these places. You can find the official Apple 
docaimentation on FindFolder at [ll. 

Under the Cocoa programming emrironment in Mac OS X, 
Apple thought you wouldn't need FindFolder, so they provided 
NSUserDefaults instead to store settings. See [2] for more info. 

I see some of you asking: “why should I care about making 
a system call to find out what I already know?" This is a common 
pitfall. Settings files should go into the System Folder:Preferences 
folder, rights Not always. Under the Brazilian version of Mac OS, 
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for instance, they should go into the Pasta do 
SistemaiPreferencias folder Besides, always making sure to call 
the proper system functions enables Apple to restructure the 
filesystem layout without breaking any software and without 
having to siippon two folder structures at the same time. 

With software that don’t call FindFolder, international users 
end up with some settings files in the correct place wliile some 
otlier software create folders with foreign names and store their 
preferences there. I'ry to explain tiiat to a user! 

A much worse situation comes up with installer software. 
Say you need to put a cenain file in a special folder, like System 
Folder:Extensions in Mac OS Classic, or to alter one of the re/ 
under the /etc in Mac OS X. if you don’t make the appropriate 
system calf your file may end up in the wrong place, and your 
software simply won't work. Please note that f as a novice Mac 
OS X programmer that we all i>ut a few Apple engineers are, 
haven't been able to find w'hat the call would Ix! to find tlie 
proper /etc direcloiy or the re.* files. Maybe it dcx^so'l even exist, 
in w^hich case Apple .should provide us with such call 

Don't Mess Things Up 

The same '‘don't mess up with the filesy.stenV’ can he .said to 
wannabe Unix developers. Developers with no previous Unix 
experience must take into account varicjus aspects of tlie Unix 
culture, especially those that have seairity implications. Apple itself 
has made some significint depiiitures from traditional Unbt practice. 

For instance, most, if not all, Unix variants have a real 
directory for /etc. With Mac OS X, Apple has decided to make 
/etc a symbolic link to /private/etc. There are other systems 
that put a symlxjlic link where a real directory would be, most 
notably Solaris witli its /bin Ixnng a link to /usr/bin, but generally 
there's a gtxjd reason for lliis kind of cTiange. 

1 don’t know what w^as Apple’s reason for putting a 
symbolic link in the place of /etc. file only thing I can think of 
is to make it easier to change most of the system's configuration 
by just making the link point elsewhere. 

But this kind of change is dangerous, given standard Unix 
programming practice and system call side effects. It must be 
done at a very c'arefuliy cixjsen lime during the Ixxjt process. It 
could also be done w^hile the system is up, but one .should be 
aware of the implications of this huge change in his or her 
panicular system. 

One problem that could appear stems from the fact that 
when a process opens a file, it gets a file descriptor that refers 
to whatever has been named by the time the open system call 
has been made. After that call, it doesn’t matter if that file is 
moved, renamed or even deleted: the file descriptor sticks with 
the originally opened file. In case of deletion, the disk space is 
freed only when all of the processes that have opened it have 
also dosed it. With all this, if one ever changes the symbolic link 
in /etc, there is tlie risk that one process, for instance, a server 
started at boot time, has a configuration file open that doesn't 
correspond to the configuration seen by all other processes 
started after the link has been changed. 

The extent of damage caused by such .situation can range 


from nothing at all to a completely disastrous cra.sh. Or, worse 
yet, it can pose a security threat, for instance, when a client 
process thinks that the server will do some sort of security 
check, while the server thinks that check to be the client’s 
responsibility. 

Don't Reinvent the Wheel 

Another departure Apple has taken from standard Unix with 
iLs Mac OS X was the use of the little known pax archiving utility 
for its installer process. I would personally have gone with tar, 
but r wouldn’t mind Apple to have chosen cpio instead, since 
these two are the formats that most (99 9 percent?) diediard Unix 
fans prefer to distribute .software in. 

With the use of pax, Apple has introduced some serious 
security flaws in their installer process. I have read a great article 
about this issue, but regrettably, I can't seem to find the UKL in 
my bookmarks. Anyway, tlie main concern in that article is that 
pax does not deal very nicely with permissions and ownership 
data about already existing directories and files. Even worse, if 
you change a directory for a symlxjlic link, pax may get 
confused and delete the link, replacing it with a real directory. 
If the link had been placed there in order to save disk space and 
have the tree below it siored in anodier disk partition or otlier 
physical disk, you will run into big trouble. 

Pax seems to have been de.signed to create aU of the 
directories and files thal il is installing, and ifs not vety^ clever to 
leave things like they are when il finds somelhing already in 
place. That w^ay, whenever you install new software, you risk 
introducing security holes that have long lieen corrected. 

Until Apple fixes tius, either by using tar or cpio instead of pax, 
or by making pax a little smaiter, we will have to double-check our 
systems every time we install .scjmething. ihe easiest w'ay to do so 
seems to l^e by looking at tlie installer fxickage, taking note of all of 
the files it adds, along with the direaories they reside in, and 
diecking for their correct ownership, |iemiii^sions and file type 
(regular file, directory, .symlxilic link, device file, etc.) Obviously, this 
w^ork would l>e much easier if you take .some lime to store all of this 
information before the installation i;ikes place and make any needed 
eorreetions afterwards. 

.Summing it All Up 

Lots of otlter aspects alxiui good development habits could 
have been mentioned here, both under Unbi and Mac OS, but a 
magazine article is just tocj short to even give a good coverage, 
let alone Ix^ing complete. The examples given here serve only 
to give you an idea of what kind of dow nturns you might run 
into by not l^eing aware of standard practice. 

But I hey also .serve to give you an idea of w'hat a 
programming philosophy is. Ifs aboul the way developers think, 
and the “right” way of doing things. Everyone will have a 
different idea of what is the “right” way of doing something, but 
some basic ideas are generally agreed upon among developers 
from a given OS. These basic ideas are what is being referred to 
here as a programming philosophy. 
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How TO Get There 

Ok, we have to develop a new programming philosophy, 
that of Mac OS X, which should be a little different from Classic 
Mac OS and from Unix, but should not steer too far from either. 
But how do we get there? That depends on whether you are 
coming from Mac OS, from some sort of Unix or you are 
completely new to both. Either way, youVe got to take a look at 
some web page from especially [4]. 

Mac OS X for Classic Mac OS Developers 

Of course Apple wouldn't succeed if they wanted us to rewrite 
all of our dependable code, dial lias cost us years of testing and 
debugging effort. But Apple can’t stand still. So, they have provided 
us with three environmenLS: Classic, Carbon and Cocoa. Ok, you’ve 
heard tliat liefore, so I’ll skip to ihe important stuff, 

Classic takes care of users. They won't have to buy new 
versions of all of their software tide before moving on to X, but 
it's discontinued now, and it's not worth writing anything new 
for that environment. Cocoa, on the other hand, is the all-new 
innovative prtigramming environment, in which all the good 
stuff is. Unfortunately for us who have invested on C, C++, 
Pascal or other languages, only Objective-C and Java APIs are 
available to work with it. 

Then, there’s Carton, The environment for those coming from 
Classic Mac OS is definitely this one. Carton is sometiiing in 
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between Classic and Cocoa. It doesn’t offer all die cool saiff diat 
Cocoa offers, but it does offer most of it, including most of the 
coolest features we’ve been hearing about Mac OS X. It allows you 
to move your applications from tlie old Classic environment widi 
little effort. Better yet, if you write for Carton, your code may to 
able to run on Mac OS 9 and, depending on the set of system calls 
you choose, even on 8.x, by just having GirbonLib installed there. 
You can learn more about it in [5]. 

You can still think of files most die same way you did befom, 
call most of yoLir favorite system calls and diink of the system mosdy 
as if it really were die familiar Mac OS you’ve always known - for a 
wliiJe. It won’t take long before you sum cursing those most words 
in die previous sentence. You’ll want to move on to Cocoa. Carlion 
is just a bridge to make that transition smcKTtlien 

And please try to stick to the rules. Leam the Aqua human 
interface guidelines (see [6]) and Quartz new^ API calls that are 
needed to implement some of Aqua look and feel (see (7l and 
[8].) Don't just use the same old ways of interfacing with the 
user Some of the old methods, like custom MDEFs or WDEFs 
won't work, anyway. 


Mac OS X for Unix Developers 

By now, you already know that Cocoa is for you. Or isn’t 
it? That depend.s on your previous knowledge of either Java 
or Ohjective-C or your willingness to learn a new 
programming language. If you already know any of these 
two languages, then look no further. You’ve got to go the 
Cocoa way, so read [91. 

Bur if you are a seasoned C, C++, Pascal, Fortran, Basic, or 
something else programmer, you might want to give Carbon a 
try, at least for a while. Be warned, though, that you’ll have a 
much harder time than your fellow Classic Mac OS programmers 
trying to go this way. ’While they already know most of the 
philosophy involved in writing good Mae OS software, you’ll 
have to leam that from die beginning. 

llie Aqua API will to something new', and don't even think 
about writing an X-windows application. Most Mac OS X 
systems won’t even have X-windows installed. But don’t let that 
discourage you. The concepts involved are very similar. You still 
have a mainO function calling an event I(x>p and acting on 
evenLs, just like on X-windows. Only the API will be new. Well, 
ncH only the API - you’ll have to play by the Aqua rules. Read 
[6]; reread 16J, then read it once again. Tired of reading? Read it 
backwards once more, just in case. It's never too much to stress 
how important the GUI rules are to keep Mac OS consistent. 

"Damn, J could forget about all this GUI stuff and write a 
character-only app," 1 hear you saying. Ok, go ahead. But don't 
forget what your intended audience is, 'fhe average Mac OS user 
doesn’t even know what a character-based UI is, let alone how 
to get to a command prompt. But if your audience is just a 
bunch of colleagues of yours and you do write a character-based 
application, please play by the traditional Unix rules, and try not 
to mess up with the System Folder or some other Mac OSisms 
brought over from Classic to Mac OS X. 
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Mac OS X for Newbies 

IF youVe read the previous sections, you stand a good 
chance of already knowing w^hich way to go. You don't know 
any programming language at ail? Learn Java and/or 
Objective-C and go the Cocoa way. You already know some 
C and only want to know what this fruit-branded OS is 
about? Ok, try Carbon. 

No marter what environment you choose to start working 
with, please, please, please! Follow the rules. All of them. 

The Bottom Line 

$ 0 , no matter what your background in some other OS 
is, if you don't have a good knowledge on both Unix and 
Mac OS standard practices, please reserve some time to learn 
about the culture on these systems. And don't try to save 
time on this] It will take lots of reading until you can say 
you’re ready to write a successful application for Mac OS X. 
If at all possible, talking to veteran developers and users 
should take much of your time, too. But you will spend 
much more time, money and effon by going ahead coding, 
writing manuals, license agreements and other 
documentation, investing on marketing and distribution, only 
to find out that the users didn’t like your software. 

Worse than that, when many developers start coding 
without regard to standard practice, eventually some of them 
will come up with exceptionally good software that users will 
like and use although it doesn’t follow standard practice. It may 
even happen with your title. But don’t be happy with that. 

When a significant number of software titles 
disregarding minimal guidelines start to gain acceptance, 
there will be nothing to call standard practice anymore. And 
Mac OS won’t have the consistency it has today. Users w'ill 
have a hard time figuring out how to use software; various 
titles wall start being incompatible wath one another. Then 
everything Apple and the Unix community across the globe 
have fought for and accomplished during many years will 
have been thrown away. 

Apple fails to comply with traditional Unix practice in a 
few spots with dangerous consequences, but those trouble 
spots are simple to fix. They seem to be doing an overaO 
good job and moving in the right direction. Let's hope that 
all - or at least most - of us wall also get this right, and let's 
make Mac OS X a success by combining the best of Classic 
Mac OS with the best that Unix has to offer And let’s not 
pour in the wajrst by accident. 
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A perfect fit! Easy to slip your iBook in and out of this 1/4" (6.5mm) 
Neoprene iBook Glove. 
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You spent how much to buy a portable computer? Then why do you 
haul a brick of a power adapter with you everywhere? This credit card 
sized power adapter makes your PowerBook truly mobile! Buy a second 
adapter for home! 
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ADVANCED 
WEBOBJECTS 5 


By Emmanuel Proulx 


Deep Into the Request/Response Loop 


Customizing Web Component 
Processing 

Preface 

This new column covers various advanced topics of 
programming Web applications with WebObjects 5- ft is 
targeted towards knowledgeable WebObjects developers 
who are looking for that extra wisdom to help them go 
further 

In this first article, I introduce the Request/Reply loop, 
and how to customize it and control how Components are 
processed, I hope this will be valuable to you. 

Overview 

From the time a user clicks on a hyperlink to the time 
the page is displayed in the browser, lots of things happen. 
Of course, the browser and the Web server first initiate the 
communication and ask for a page. If you installed 
WebObjects with the CGI adaptor (as opposed to a native 
one), the following type of URL is used: 

http://server.domain.subdomain/cgibin/WebObjects/ApplicationN 

ame 

Here the WebObjects adaptor program is being called, 
and if there is an application called “ApplicationName” 
registered, it is being executed. WebObjects builds a page 
and returns it, calling your code to fill in the blanks* Thi.s part 
is very transparent. But the building of a page is not. How 
does it work? What happens? When does it happen? 

Knowing the answer to the.se que.stions is important to 
expand, tweak and adapt your WebObjects program to the 
specific requirements of your target system. Figure 1 
illustrates how^ it works: 



Figure L Objects of the Requesi/Response Loop. 


The WebObjects adaptor program builds a Request 
object, which encapsulates the original '‘Get/Post*' message 
received by the Web Ser%'er. This object is passed around the 
framework as WebObjects works on the Component (page 
template). Then WebObjects builds the Response object, 
which encapsulates the returned (pure HTML) page. 

During this time, many classes of the framework call 
each other. You know about the Application and Session 
classes. You just learned about the Request, Response and 
Component classes. When they interact, they call different 
functions at different times. 

Knowing when the functions are called and overriding 
the correct function is the key to customizing the 
request/response loop. Figure 2 illustrates the different 
objects and methods and their interactions. The next sections 
describe them further, and prescribe when to overload them. 


Emmanuei Froubs is a Course Writer, Author and Web Developer, working in the domain of Java Application Servers, He can be reached at 
emmanuelp@theglobe.com, 
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Figure Z lntenicti(nis Betu^^ Melhods. 


AmiomoN Object 

The Application class is a subclass of the virtual 
WOApplication class. Your Application class will only have a 
single instance per server This class contains the main() function. 
By default, the generated code for this function calls 
WOApplication.main(), which creates a Singleton instance of your 
Application class. You have to use the following definition so 
your subclass will be recognized: 

public class Application extends WOApplication 

I have also stated that the Application object is accessible 
from all Sessions on the server, and its main use is to share data 
among them, and to hold global business logic. Ihe Application’s 
underling goal is to manage the Sessions and the 
requesi/response loop. Typically, you overload at the Application 
level if your code is general to all clients. That said, here are the 
main functions that you can overload to customize tlie 
framework to your needs: 

• niain(Stfing []) : Overload to initialize variables before the 
system is started. Note that the default behavior is to call 
WOApplication.mainO, which creates an instance of 
Application. 

• AppiicationO (Constructor): Ideal to put the system-wide 
initialization code. 

• haiidleRequest(WOReque$t): Takes care of a single iteration 
of the request/response loop. The base implementation calls 
awakeC), takeValuesFromKequestO, invokeActionO, 
appendToResponseO and finally sleepO, 

• awake():Ca]led by the framework when there’s a new 
request, before WebObjects begins processing it. Overload 
for example when you want to keep statistics of the 
frequency at which the system is being used. 

• takeValuesFromRequest(WORequest, WOContext): The base 
itiiplementation calls Session. takeValuesFromRequestO^ As its 
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StoneTable 

You thought it was just a replacement 
for the List Manager ? 

We iied, it is much more ! 

Tired of always adding just one more feature to your LDEF or 
table code ? What do you need in your table ? 

Pictures and Icons and Checkboxes ? 
adjustable columns or rows ? 

Titles for columns or rows ? 

In-line editing of cell text ? 

More than 32K of data ? 

Color and styles ? 

Sorting ? 

More ?? 

How much longer does the list need to be to make It worth 
$200 of your time ? 

See just how long the list is for StoneTable. 

Make StoneTable part of your toolbox today I 

Only $200.00 MasterCard & Visa accepted. 

StoneTable! Publishing 
More Info & demo Voice/FAX (503) 287-3424 

http://www.teleport.com/--stack Stack ©teleport.com 
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name stipulates, tills function should be overridden when you 
want to process the request object from the application object. 

• WOResponse lnfokeAction(WORequest, WOContext): The 
base implementation executes the action associated to a 
Request, by calling Session.invokeActionC). Ttiis function 
should be overridden if you intend to act upon the action 
itself (for example, to stop one from being executed). 

■ appendToResponse(WOResponse, WOContext): The base 
implementation calls Session.appendToResponse(). As its 
name says, tliis function should be overridden to add to the 
Response, or for any post-action operation. 

• sleep(): Called by the framework after a request/response is 
done with, before WebObjects waits for the next one. 
Overload for example when you want to keep statistics of 
tlie requests duration. 

• finatize(): The Application's destructor hinaion is ideal to put 
the system-wide cleanup code. 

Session Object 

The Session object is a subclass of the virtual WOSession 
class. Your Session class has one instance per HTTP connection. 
WebObjects creates all instances for you, but you have to use the 
following definition: 

public class Session extends WOSession 

The main use of the Session class is to hold connection- 
specific information and business logic. Under the hood, it's also 
in charge of terminating itself and holding the Editing Context 
(database objects). You will notice that most of tlie functions you 
can overload are similar to the Applicalion's. This is so you can 
decide die scope of your cwerloaded code, Typically, you 
overload at the Session level if the code is connection- or client- 
specific. The interesting functions are: 

■ SessionO (Constructor): The constriJCtor is called a single 
time shortly after WOApplication.awakeO is called, but won't 
be called again for the current client. This function is ideal to 
put the connection-specific initialisation code. 

• awake(): Called by the framework when there's a new^ 
request, during WO Application, a wake(), before WebObjects 
begins processing the request. The base impleiiientation calls 
WOComponent.awakeO. Overload to call request-specific 
initializiition code. 

• takeValue$FromR&quest(WORequest, WOContext): Called 
during Application.take ValuesFromRequestO. The base 
implementation calls takeValuesFroml^equestO.in the page tliat 
was requested. Tliis Rinction should be overridden when you 
want to process the Request object iTom tlie Session object. 

• WOResponse lnfokeAction(WOReque5t, WOContext): Called 
during Application.invokeActionO- The base implementation 
executes tJie action associated to a Request by calling 
invokeActionO in the page that was requested. This function 
should l^e overridden if you intend to act upon the action 
itself (for example, to .stop one from being executed), 
depending on a client-specific state. 


< appendToResponse(WOResponse, WOContext): Called 
during WOApplicaiion.appendToEesponseO. The base 
implementation calls appendToResponseO in the page that 
was requested. Tliis function should be overridden to add to 
the Response, or for any post-action operation. 

• sleepf): Called by WO Application. sleepO after a 
request/response is done with, Itefore WebObjects waits for 
tlie next one. 

• fmallzef): The Session’s destmctor ftinction is ideal to put 
client-specific cleanup code. 

Web Component 

The Component objects are subclasses of the virtual 
WOComponent class. There can be multiple instances of a 
Component, and they are usually represented by local 
references. 

WebObjects creates an instance of the Component with the 
name “Main" for you, returning it to the client browser, bui you 
have to use the following definition: 

piiblic: class Main extends WOComponent 

You are responsible for ereaiing instances of other 
Components. Usually, a Compcinent is returned when an action 
is invoked. In that ease, you create an instance of a Component 
by using this syntax: 

WOComponent an/lctionO [ 

rettirn pa geWithMame t" : 

] 

The main use of the WOComponent suWass is to hold 
page-specific ckita and logic. On top of that, Components have 
the ability to generate the result page (using method 
generateResponseO). Again, most of the functions you can 
overload are similar to the Application's and the Session’s. 
Typically, you overload at the Component level if the code is 
page-specific. The functions you can overload are: 

• Web Component Constructor: The constmctor is called when 
pageWithNameO is called. Tliis function is ideal to put the 
page-specific one-time initialization code Use awakeO to put 
page-specific per-request initialization code. 

• awake(): Called by tfie framework when there's a new* 
request, during WOSession.awakeO, before WebObjects 
begins processing the request. The base implementation 
does nothing. Overload to eal! page-specific per-request 
initialization code. 

• takeValuesFromRBquest(WOReqijest, WOContext): Called 
during WOSessionlakeValuesFromRequestO. The base 
Impiementation calls WOEIement.takeValuesFromRequest(), 
where WOElement is the root element (<BODY>) of the 
hierarchy of the page. The function is then called recursively 
on each element of the hierarchy. Tliis function should be 
ovenidden when you want to process the Request object 
from the ciiirent page. 
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At REAL Software, we like it simple. Take our award-winning product, REALbasic, for 
example. People call it the powerful, easy-to-use tool for creating their own software for 
Macintosh, Mac OS X and Windows. We call it a problem solver. You've probably said, 
"Wouldn't it be great if there was a little application that...." REALbasic fills that blank. 

It's powerful and it's intuitive. Beginners and professionals alike can build software 
using a single, simple design. REALbasic compiles native applications for Macintosh, 
Mac OS X and Windows without requiring any platform-specific adjustments. Each 
version of your software looks and works just as it should in each environment. 

Experiment, explore, learn and innovate as you create anything from prototypes to 
complete professiona! quality applications step by step. Simply drag and drop interface 
elements while REALbasic handles the details. You concentrate on what makes your 
stuff great — your ideas! 

Complex problems shouldn't require complex solutions. The answer is REALbasic 


Q REALbasic3.5 


Download a free demo, www.realbasic.com 



• WOResponse infokeAGtion( WO Request, WOContext): Called 
during WOSession.invokeAciionO. The ba.se implementation 
executes the action associated to a Request directly. This 
function should be overridden if you intend to act upon the 
action iLself (for example, to stop one from being executed), 
depending on a page-specific state. 

• appendTaRe$ponse(WOResponse, WOContext): Called during 
WOSession.appendToResponseC). The base implementation 
calls WOElement. appendToRespooseOt where WOElemeni is 
the root element (<BODY>) of the hierarchy of the page. The 
function is then c-alled recursively on each element of the 
hierarchy. This function should be overridden to add to the 
Response, or for any post^action operation. 

• sleepO' Called by WOSession.sleepO after a request/response 
is done with, before WebObjects waits for tlie next one. Ideal 
for per-requesi page-specific cleanup code. 

» finaliie(): The Component’s destructor function is ideal to put 
one-time page-specific cleanup code. Use sleep() to call per- 
requesi page-specific cleanup code. 

Element Object 

There's an object tliat I skipped on purpose here, the 
WOEIement object. You usually don't subclass this class, unless 
you want to write your own customized elements. You can 
avoid this troul>le by using custom components instead, which 
is easier to write. The interesting member functions are the 
constructof, takeVa(uesFromRequest(), invokeAction(), 
appendToResponseO and finalize(). The usage of these functions 
should be trivial. 

Request Object 

As stated before, the Request class encapsulates a Get or a 
Post HTfP request. The base class for WORequest is 
WOMessage, so some of the characteristics explained here are 
inherited from that base class. 

The framework uses an in.sianL'e of WORequest to pass it 
around during tiie pre-generation phase (awakaO, 
takeValuesFromRequestO and invokeAclion() funaions), Here's a 
p;u1ial list of the information held in tliis class: 

• A list of “cookies'* (cookies are key/vafue pairs stored in the 
client's Browser). Keys are user-defined only. Cookies will he 
discussed in their own seaion, 

• A list of all submitied form fields when appiicable (Post 
request only). Form fields will be dLscussed later on, 

• A list of “headers” (headers are key/value pairs containing 
tlie context of the request). 

• Tlie hits that make up the requested URL. 

• Other request information (encoding, languages, protocol, 
request type). 

I will skip cookies and form fields; they are covered later 
on. As for headers and the other information, there’s no 


prescribed way of using these. It's up to you to figure out how 
to use them in your advantage. I can only show you how to 
access them. Following is an overview of the available ftinctions. 

Headers 

Accessing headers is done with these functions of the class 
WORequest: 

• NSArray headerKeys Q: Returns a list of all available header 
names as Strings. Use these as keys in functions 
headerForKeyO and headersForKeyO, 

• String headerFdrKey(Slring) and NSArray headersFoiKeyfString): 
These functions netum the value (or values) of a header, when 
you pass tlie header’s name (key). Use the fust for single-value 
headers, and the second for multiple values. 

Bui wliai are the fundamental request headers and what are 
they used for? Here’s a link diat lists some of the basic request 
headers: 

http://wwvv.vv3.org/ProtocotsiHTTP/HTRQ_Headers.html 

But there may be other headers, because some are specific to 
the Web browser. To find out alx>ut those extra headers, the fu^t 
thing that comes to mind is to overload takeValuesFromRequest() in 
one of Application, Session or Main, and print them out. The 
following piece of code does exactly tliat: 

public void takEValuesFramRec|uest(WORequest r, WOCoittext c) 

( 

super,takeValuesFron^equest(r.c); 

if(r.headerKeys() = null) return; 

forfint i< r.headerKeysO .count0 : i++) I 

String key “ (String)r.headerKeys t) .objectAtlndex(i); 
NSArray values = r.headersForKey(key): 

System.out.println(“Found header “ + key t 
” : “ + value. toStringO ): 

[ 

1 

Here's what the output might look like: 

Found header: accept charset “ (“iso-8359-1,* 

Found header; accept -language = (bg) 

Found header; accept-encoding = (g^ip) 

Found header; connection = ("keep-alive'*) 

Found header: user agent ” (“Hozilla/4.6 [en] (UinNT; I)“J 
Found header: host ^ (“localhost:3fl78"} 

Found header: accept ^ ("image/gif, image/x-xbitmap. 
image/jpeg, image/pjpeg, image/png, V'“) 

Found header: referer = 

("http;//www.imaginarypenda.com/gotoslte.html”) 

Dismantling URLs 

Next, let’s have a look at the functions retuming the parts 
of the requested URL. Lefs use an example for each function. 
Imagine the user wrote the address: 
http;//www.imaginarypenda.com/cgi'bin/WebObjects/App 
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Here are the methods of WORequest to take a URL apart: 

• String uriQr Returns the last part of the whole URL, from the 
first slash to the end. For example, if the user typed the URL 
above, this method should return “/cghbin/WebObjects/App”. 

• String adaptorPrefix(]: Provides the acJaptor’s name. For 
example it could be Vcgi-bin/WebObjects/” on Mac OS X or 
Unix, or ‘^/cgi-bin/WebObjects.exe/’’ on Windows. This 
example shows the CGI adaptor prefix; it may be different if 
using a native Web server adaptor. 

• String appllcatloNumberO: Returns the user-requested 
application number, when provided. This infomiation is 
usually not provided by the user in the URL (as not shown 
above). In these cases, this functions returns -1 and meaning 
any one instance of the application was called. 

• String applicationName(): Returns die application's name. In 
our example, it is “App". 

Let’s dissect some URLs and see wliich function reairn 

which part. Here are three examples. 

• The first example below sho%vs a MacOS X-based server, 
pointing to any instance of Find-A-Luv (no instance number). 
In this case, applicationNumbeit) wiU return -1. 


• The second Ls a Windows-based server, pointing to any 
instance (we could have skipped the -1). 

• The third is a Unix-based server, with native adaptor (no CGI 
involved), and pointing to the third instance, 

http://vww.aUrl-coDi /cgi-bin/WebObjects/ 

Find-A-Luv 

http://www.aUrl.com /cgi-bin/WebOhjects.exe/ 

-1/ Find-A-Luv 

http://ww.aUrl.com /WebObjects/ 3 Ftnd-A-Liiv 

adaptarPreflx() appllcatiotiNumber () applicationName () 

uriO 

Other Request Info 

Following is an brief overview the “other information" 
hinctions: 

• methodO 

StringAny valid HTTP mediod, like “GET”, “PUT, “POST’, 
"HEAD", etc. See http:/AAAAAiv.w3.org/Protocols/HTTP/ Methodshtml for 
a complete list of methods and their usage. 

• browserLanguagesO 

NSArray of String 'fhe list of languages (see your 
browser’s language preferences). 
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• contentO 

NSData Always null unless there was raw data posted 
with the request. 

• httpVerslonO 

String For example, ''HTTP/LO”. 

• userlnfo{) 

NSDictionary A set of key/value pairs, passed around 
during the processing of die request. Empty by default, but 
you can use it to convey data around the framework. 

I don't want to spend too much spac'e on these functions 
since their usefulness is limited. 

Response Object 

The Request's counteqiarl is the Response object, which 
encapsulates the page returned to the requesting browser. The 
WOResponse class is also a subclass of WOMessage, so some of 
the characteri-stics well cover come from that base class. 

Typically, the Response object is created by the framework 
and passed around the elements hierarchy during the generation 
phase. Then it is passed to the Component, Session and 
Application objects, during the post-generation phase. All of this 
is accomplished by function appendToResponse(). 

The information in this object is very similar to the Request 
object. 1 lie difference is that you can change this inf'ormation, 
and write to the buffer holding the returned page. Here’s an 
overview of die kind of mfomiaiion you am get and set: 

• A list of cookies. Cookies will be discussed in dieir own 
section. 

• A list of resulting headers. 

• The actual contents of the returned page. 

• Other request information (status, encoding, protocol). 

Response Headers 

We saw how to get headers in previous sections. Tlie same 
getter functions exist in the WOResponse object (headerKeys{), 
headerForKeyO, headersForKeyQ). On top of that, you can set the 
headers returned to the browser: 

setHeacier(Strlng value, String key) and setHeaders(NSArray 
values, String key): These functions fix the value (or values) 
of a header, given its name (key). Use the first for single¬ 
value headers; use the second for multiple values. 

A list of basic response headers can be seen at: 
http://vvww.w3.ofg/Protocols/HTTP/Object_Headers.html 


Response Text 

For getting and setting the contents of the returned page, 
WOResponse lias many methods. Here are a few of them: 

• KSData contentsQ: The raw bytes that constitute die returned 
HTML. An NSData object encapsulates an array of bytes (byte 
D, and the interesdng functions are bytesO and lengthO- 

• setContent(NSData): Replaces the whole returned page with 
die one you provide, 

• appendContentString(String): Adds the specified string to the 
end of die resulting page without changing anything, 

■ apperidCoriten1HTMLString(S^ Adds the specified string to 
the end of the page, but escapes the HTML-specific characters. 
For example, the charaaer will be changed to 'Slf. 

WARNING: you usually don’t want to use S8tContent() 
because it wipes out the previously computed HTML. Use the 
append...() methods instead. 

Other Response Info 

The ‘'other informadon” methcxls of WOResponse include: 

• defauREncodingO 

5etDefaultEncoding(int) Gets and sets the default encoding, 
specifying the character set that should lie used by die 
returned contents. 

• contentEncodingQ 

setContent£ncodmg(int} Gets and sets the encoding, specifying 
die character set that is being used by the relumed contents, 

• httpVerslonO Gets and sets the a string indicating the 
protocol format 

• statusO 

setStatus(int) Gets and sets the status, indicating if the 
generation was successful (status() returns 200) or if an error 
occurred. See this page for a list of status codes: 
http://www.w3.org/Protocols/HTTP/HTRESRhtml 

• userlnfoQ 

setUserlnfcKNSDiotionary) A set of key/value pairs, 

passed around during the processing of the response. Empty by 
default, but you can use it to convey data aiound the framework. 

Conclusion 

As you've seen here, there is more to a request/response 
loop than simply asking for a page and getting the HTML back. 
Many objects and methods are called along the way. As weVe 
seen, most of the methods can be overloaded to intervene in 
the loop at a specific moment. WeVe also looked at the ways 
to manipulate the request and response themselves. Again, 
what to do with this knowledge is up to you, but I can almost 
hear your brain pondering. Ki 
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MAC OS X 


By Andrew C. Stone 


Internationalizing Cocoa Applications - A 
Primer for Developers and End Localizers 


Now dial you have written that amazing objea-orieoted Cocx^ 
application, it's time to bring tiie fruits of your creativity to the rest 
of the planet. This article has two components: the steps a 
developer needs to Lake to allow tlie application to be traaslated, 
and the steps the translator perfomis to localize an application to 
another language. Wliiit sees Cocoa localization apart iron other 
development environment localization systems is iLs pure simplicity. 
Onc’e an appUcation has been prepared to lie kxidizable by a 
developer any number of languages can lie added to the final 
prcxluct, without any recompiJing by the developer or any access to 
the source by the parties who are doing die tmaslations. In faa, the 
kx:alizer can lie a regular end user with a love of native language 
Mac OS X appliotions! These facts signif^^ tliat you can ship your 
application in your native language, and then begin the process of 
internationalization afterwards. We'll examine whaf die developer 
lias to do, and then the steps required by die localizer 

Making An AppuomoN Locauzable 

Translatable text in a graphical user inteiface appears in two 
places: the Interface Builder files (nibs) which display menus and 
interfaces, and die emliedded strings that are used in 
programmatically-creiited alert and dialog windows. A developer 
who follows a few guidelines will aciually have no additional work 
to perform to kx.'iilize tlieir application: 

• Make all progiammaiic text, alert p^inefs tides, messages and 
buttons use translation macros instead of quoted English strings 

• Always add interface files as lcK:alizabie resourc'es 

IVlANSlAIABLE DICTIONARIES - THE FILES 

As you write your code, whenever you use a string that’s 
going to be displayed to the user, use one of the NSLocafizedStnng 
macros (NSLocalizedString, NSLocalizedStringFromTable, 
NSLocaNzedStringFromTableInBundle), When your code is 
executed, these macros look up the string in a dictionary file with 
a “.strings’" file ending. The .strings file is generated by a 
command line program, genstrings, diat processes your code 


looking for die macros. Thus, there are three steps to creating the 
strings files that get added to the English.lproj (wel use English 
as die native language in this article, although you can develop in 
any language using Projea Builder); 

• Use the NSLotalizedString* macros in your code 

• Run genstrings to generate the .strings files 

• Add the generated files to your PB project as localizable 
resources 

Here is a sample line of code, a message to set what the Undo 
menu displays once diis action lias been performed, wliicli will 
appear in die user's chosen language: 

[[self undoManager] 

setActiciTiNaiiie:NSLocaiizedStriTigFromTable(@"Change Print Info", 
@'*Huktiiiatli“» ©"Action name for changing print info.")]; 

NSLocalizedStiingFiomTableO takes die siring to be displayed 
(^'Change Print Info”), die table to look for the string in 
(Muktinath.strings), and a helpful comment for the person who is 
translating die phrase. 

Running geiistrings on this code would produce an enUry in tlie 
Muktinath.strings table:\ 

Action mrac for dianging print info. 7 
‘‘Change Print Info" = “Change Print Info": 

The translator vould then m^e a copy of the .strings file and 
translate the right hand side. For example, en Espalng 1 
Action name for changing prim info, V 
"Change Print Info" = "Carabiar Info de Imprimir": 

When using the macros in llie standard alert panel, one 
teclinique to make your code easier to read is to use ^defines, which 
also allows easy reuse: 

/Meflne TERMINATE_TITLE NSLocalizedStringFromTable(©"Quit”. 
©"Packlt", “Title of alert panel") 

^'/define TERMINATE_MSG NSLacallzedStrlngFromTable (©"Remove 

temporary files7“, ©"Packit", “Message when temp files exist") 


Andrew Stone <andrew@stoaexom> is founder of Stone Design Corp <http://www.scone.coni/> and divides his time between farming on the 
earth and in cyperspace. 
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^define CANCEL NSLocali^edStriiigFromTable(@“Leave alone"* 
@"PackIt"* "Button title to not remove the files") 

^define OK NSLocalizedStringFr:ojnTable(@''OK''.@”PackIt" * "Button 
choice for 0K*ing a requested operation.") 

"if 

(NSRunAlert Panel (TERMINATE_TITLE,TERMINATE_MSG* OK, CANCEL. NULL) = 
NSA1e rtDefaultReturn) 


Generating toe Sitiings files: genstrings 
Once you have removed all diieit uses of English strings in 
your program, then you are ready to a)llea all tlie transhtnble 
strings into tlieir .strings files. 

Type "genstrlngs" In a tennlnal window to see its options: 

Usage: genstrings [-J] [-a <routine'name>] [-0 <output 
directory)] fllel*[mcj ,,, fllen.[me] 

Help: genstrings generates *strings file(a) from your source 
code* 

The names of your source files are the arguments: filel 
*** fllen. 

• C and Objactive-C: 

Source lines with NSLocalizedString(string* comment) 

will 

generate an appropriate string table entry on 
Locallzable.strings. 

Source lines with NSLocalizedStringFromTable(string* 
tablename, comment) 

will generate an appropriate Etring table entry in 
tablename.strings. 

Source lines with 

NSLocalizedStringFromTableInBundle{string* tablcname* bundle, 
comment) 

will generate an appropriate string table entry in 
tablename-strings. 

* Java; 

The 'j option sets the expected Input language to Java, 
In this case the above 

keywords are changed to Bundle*localizedString. 

Bundle.lacalizedStringFromTable. 

and Bundle.localizedStringFromTablelnBundle (inatead 
of the Objective-C defaults)* 

The -s option subEtltutes its argument for 
NBLocalizedSt ring * 

For example* -s MyLocalString will catch calls to 
MyLocalString 

and MyLocalStringFromTable, 

The ^0 option specifies what directory tables should be 
created in* 

A simple invocation for a multi-level Objective C projea would 
be sometliing like: 

genstrings *[hmc] •/•[hmc] '/‘/‘[hme] 

All soLiPce files in the top three levels would be searched to 
produce the output strings file. Add the produced .strings files to 
your resources folder in Groups 8l Files in Project Builder, and then 
make them kxalizable* as described in the next section. 

Making FiLES Localezable 

The developer’s second major job is to add all translatable 
Interface Builder files as iocalizable^ tn Project Builder: 

• 1. Add the new interface? file (Project -> Add Files... or just drop 
it in to Groups & Files outline view -1 like to place .nibs into 
“Resources”* 
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If you liave saved the .nib file in EnglLsh.lpnoj - then steps 2. 
and 3. are not necessary, otherwise: 

■ 2. Project -> Into to bring up interface iaspector 
• 3. Click ^Uxralization Sc Platfoims" popup * choose *'Make 
Lcxiilized'’ 
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Add Platform Variant... 


Adding other language of the interfaces is done with 

Project->Info with the file to localize seleaed. 


This moves the interface hie to tJie EnglLshJproj in our 
example. To add a new language versitm, select tl'ie interface tile in 
Groups & Files, chcxxse "Add Ltx’aMzed Variant...'' from Qie 
"LcK'alization and Platforms” popup and type in liie name of itie 
language in English (example, for Espao the EnglishJprcjj in our 
example. To add a new language version* .select the interface file in 
Groups 8l Files, choose "Add Localized Variant..*" from the 
"Localization and Platforms” popup and type in the name of the 
languager of the user’s language preferencx^s, if thcxse languages 
exist in tlie projea. The same prf)cediire applies to .strings files and 
otlier resources that require kx:aliization. Ihe iot^ilizer now has the 
resources needed to translate the prognim. 

End User Localization - Anyone can do this! 

Localizing an application can l^e done by anyone who lias a 
[yasic loiowledge of Interiace 13uilder, TextEdit, Terminal imd how to 
open Tile packages in Finder. Interfiice Builder comes on the 
LVvelopcr CD that sliipptd with the original OS X 10.0, so you 11 
need to iastall die Developer package il' you liavenT :.dityady. A 
tnmslator dcxisn’t even need to know how to use InierfaccBuilder il' 
the developer extracts the kxralizable strings Itorn die interfaces widi 
a speclil t(X)l, niblooi descrilied in the Advanced section lielow. 

First, copy the application you wish to kxiilize, ju.st in case you 
mess something up! Since you will be editing hies iaside of the 
Application wrapper, you may to set tine pemiissioas .so that you II 
lie able to save the changes: 

1. Launch/Appiicarions/Dtilities/Temiinal 

2. Cliange dbectory to where you copied the apidication 
cd <DlRECrORY> 

3. Change pennissions to ahew saving: 
climod -R a+rwX <APPLlCAT’ION>*app 

Now, you need to open die application wrapper. In Finder, 
hold down the control key while clicking on die application file and 
chtxjse "Show Package Contents” from die ctintextual menu: 


.B8 m mj i 'S tjt ^ ^ 

Back_View _| Cwnpulef_ Home FivofItci AppUCAtisns 

7 tteml, 1CB milabte 
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i Duplicate 
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Help 
Open 

Move To Trash 


Show Package Contents e 



Kind: Appllcitlofi 

ControhClick an applimtion to open it up 


To lest your application, set the system language to the one you 
are kx:ali7jng* In System Pieferences, International Pane, drag the 
language of choice to the top of the list: 
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Be mre to set yemr language before V(^u kmneb our test 
aiplication/f 


All OS X application has one folder, “(xintenLs". Inside of that 
fuidcr is “Resources”. In Resources, you’ll find English.Iproj. This 
folder should lie duplicated, and tlien mnamed to the English 
version of your language, e*g. SpanishlpR)], Dutchlproj, 
Hrench.lproj, Japanese.Ipioj, Gemian.lproj, lUilian.lproj, etc. 

Now you can edit all die files in your language’s .Ipraj directory 
and test your application by laundiing it anew'! 

6 items, 1.1 GB available 

« Crediis*rif 
B CIFfun.nib 
Glffun. strings 
B GIFPrefs,nlb 
B Infomlb 
, InfoPtist.strings 

f 

Kind: Interface 
Builder 
Document 

There are three t)pes of files to edit: strings, jjih, and Mml/fif 
i7iformational/}?elp files. 
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Tbe -strings Vmm 

The most tering task is to convert tlie strings which appear 
programmatically: the titles, messages, buttons from alert panels, 
and the ‘"action names'’ that the Undo system uses to keep a track 
of what it’s undoing. (For example, if you change the way the page 
was layed out, the Edit menu would display “Undo Cliange Print 
Info”.) Sophisticated software like Stone Design’s Create® may 
have hundrcxls of operations tliat can be perfonned, and require 
translation. Smaller applications may have very few of these, so 
don’t get discouraged] 

These strings appear in .strings files in tfie .Iproj directories. You 
can use the free, Apple-provided, and Ccxxxi-l:)ased TextEdit 
program to edit these files; TextEdit supports unictxie, the lingua 
franca of the Cocoa Text system, so ail of the special character) 
found in other languages will be conectiy preserved. Because the 
.strings extension is not regi.stered with TextEdit, double-ciicking a 
.strings fde brings up the There is no appliotion available to open 
the document “Something.strings”- “Choose Application’” dialog. To 
avoid this, place TextEdit in your dock, and drag the .strings file on 
top of the TextEdit icon to quickly open the file. 

On the left liand side of a typical entry in die .strings file, the 
development language string appears, in quotes, followed by an 
equals sign. Ttie right hand side of tlie entry is to Ix" replaced by the 
ecjuivalent phrase in your language. Finally, because diese l^es need 
to fx easily parsed l)y the applicaticm, die entry ends in a semi- 
cT)lon, and uses /* and */ to delimir comments: 

/* Name of Jksoiirxr Source - like Patterns V 
"Pattern" = "Pattern": 

So I the French localizer would translate the second, half Into: 
"Pattern^* “ "Texture": 

And the Spanish localizer: 

"Pattern" = "Motive": 

And the German localizer: 

"Pattern" = "Muster": 

One note atxiul tr:aaslatirig strings Is tlie occurrence of format 
strings witliin tlie quotes. Hie prognimmer can use %f and 

other “sprintT-style placeholders to place runtime infomiation in tlie 
programmatically-generated text. For example, tlie following string 
will display die name of the pattern: 

/* aiert message: lo prcvcnt rcmfnral of default pattern 7 

“You cannot delete the W pattern." = “You cannot delete the %0 
pattern. 

Wlien the prognim is mnning, die message wtjuld luplace the 

with the actual name of the pattern that cunnol lx* deleted. 

The localizer must take care to preserve the nunilier and 
order of these placeholders. Programmers should make this 
easier for translators by providing info on the parameters in the 
comments. In the case of multiple parameters, the parameters 
are passed in order, and localizers need to keep this mind, even 
if it means awkward sentence structure, because otherwise, the 
program will crash! Be careful 

lb insert quotes into tlie quoted string prefix the quote with a 
backsksh: “'Ihe word \”quotes\” is quoted.” To insert a single, literal 


'W in a string, use “%P/o”. 

Besides the genstrings-produced ..strings files, there is aiso an 
InfoPlist.strings file which has a few strings that can be localized: 

i 

CFBundleGetInfoStriug = "Stone Desigti's Create®. S 1990- 
2001, Stone Design Corp. Visit www.stone.com"; 

NSHumanReadableCopyright = "© 1990-2001, Stone Design 
Corp.\nVislt ww.stone.com": 

// Doaimem typt humaiHmIable names. 

"Stone Design Graphic Format" = "Stone Create (creB)": 
"NSPDFFboatdType" = "Portable Doeument Format (PDF)"; 
"NSTIFFFboardType" = “Tagged Image File Format (TIFF)": 
CFBundleHelpBookMame = "Create Online Manual"; 

CFAppleHeIpAnchor = "GreateHelp"; 

} 

By translating the file types such as “NSPDFl^boardType”, you 
can have more attractive popups in your Save panels. The 
CFBundleHelpBookName key conUoLs the display title of the Apple 
Viewer help your application provide.s and should he translated. 

Tm M:erfaces - Using iNimpACE Buiu>er 

Now comes the ftin part! Interface Builder lets you open and 
edit the .nib (NeXT Interface Builder) files, which are the actual 
interfaces used by a program. To give yourself a real Ixiost, first 
tmnslate the nib that contains the main menu, usually named the 
same as the application, e.g. “GiFfun.nib”: 

'the process of converting tlie IB files goes like tliis: 

for each IB file do: 

• For each string you see, double-click it to edit, and replace with 
a translated word or phrase 

• If necessary resize the control according to the feedback 
provided by IB 

• If an interface element has a help tip, translate tliat as well 
Save and test by quitting and relaunching the applic^ation 

A few fine fxiints: 

• You can tab between menu and matrix items to increase 
editing speed 

• To set the title of a window, click on the window, select Tools- 
>Show Info, and select “Attributes” in the |X)pup 

• Note tiiat IB (and OS X) requires that you I'd! <RtTllJI^N> or 
<TAB> to make your edits “stick". 

• Don’t Ibiget to translate each pane in a Tab View: Double-click 
each tall to make its pane visible 

Each interface element can liave an attached Help Tip - tliose 
cute little yeOow windows tliat pop up if you leave your mouse over 
a control for a few sexonds that descrilx the functionality of die 
coelix)!. To change these: 

• Select tile control 

• Tcx)ls->.Show Infb) “Help” p<.>pup p^me 

• Enter the tip in your language, and be sure to hit <REniRN> to 
make it stick 


Advanced laxiwuEZAnoN Tones: Bundies, Nimxx>L and Appie 
Viewer Help 

As usual, the simple life ain’t so simple! One thing to 
watch for is good engineering on the part of the developer. 
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Cocoa is a dynamic, runtime bound system, which means that 
objects (code and interfaces) can be loaded upon demand, not 
when the program starts. In Create®, for example, there are 50 
interfaces which are dynamically loaded. This means very fast 
launch times, and much better memory usage, because you 
only load resources that you use as you use them. These 
**bundles"' are layed out in a similar manner to the packaging 
of the application; each .bundle folder contains a Contents 
folder, which has the Resources folder, which contains an 
English.Iproj witii all localizable resources for that bundle. Most 
bundles just have one nib file — but you need to repeal the 
process described above (duplicate the English.Iproj, rename it 
to your language in English, and localize the files in the 
<LANGIJAGE>. Iproj) for each .bundle folder in the 
application's Resources folder 

With the introduction of InterfaceBuilder 2.1, Apple has 
provided localization capabilities to the command line utility 
named nibtool (/usr/l^in/nibtool). liibtool can extract the 
localizable .strings in a nib to a .strings file, which can be 
translated, and then reincorporated into a copy of the nib file. 
This will not adjust spacing of the U1 elements so it"s just a start, 
but it might help things go faster. 

To geneiute the strings file for a particular nib file: 

nltitool -L myflle.nib > file.atrings 

file.strings will now' contain entries such as “key" = “key" and 
lx? in Unicode (Ul’F-lh) fonnat. Next, give die resulting .string.s file 
to a traaslator and liave them convert the second “key” entry to “key 
in otlier language” 

To reincorporate tliese translated strings: 
nibtoal -d file.strings -w newLocallKation.nib tnyfile.nib 

nibtool will take tlie contents of file.strings and replace “key” 
in myfile.nil'> witli “someQiing in oilier language"" in the translated 
version “newLcx^alization, nib”. 

Tile final, and most demanding, part of the translation i.s die 
Online Help system - the folder of linked .html files that contains 
a special “Sherlock-style"' index for instant searching. Stone 
Design keeps our help files in Create®, the localizer then edits 
the help direcdy, and produces the HTML with a simple export. 
This is usually easier than hand-hacking html liecause you also 
want to change the streenshots to reflect the translated 
interfaces. Please read my MacTech article of a few months ago 
entitled “Help On The Way! A guide for the perplexed on adding 
Apple Help to your OS X application” for complete instructions 
on adding online help to an application. 

CCWVCLIISK)N 

OS X has complete support for internationalization and is 
simple enougli that end users can add new' languages. With a small 
amount of effort, developers can produce applications which can be 
translated to new languages out in the freld, witliout access to source 
code, by regular yet adventurous users. ffij 
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QUICKTIME 

TOOLKIT 


By Tim Monroe 


F/X 


Using Video Effects in QuickTime Movies 


Introduction 

The QuickTime video effects architecture, introduced in 
QuickTime 3, is an extensible system for applying video 
effects to single images or video tracks (called filters), and to 
pairs of images or video tracks (called transitions), 
QuickTime includes an implementation of the 133 standard 
transitions defined by the Society of Motion Picmre and 
Television Engineers (SMPTE), as well as some additional 
effects developed by the QuickTime team. The SMPTE effects 
include various forms of wipe effects, iris effects, radial 
effects, and matrix effects. Of all of these, my personal 
favorite is a wipe effect called the horizontal barn zig-zag, 
shown in Figure 1, 



Tlie additional QuickTime effects include transitions like a 
simple exldode (where the first image is expkxled outward to 
reveal the second image) and a push (where the first image is 
pushed aside by the second image). Figures 2 and 3 show these 
effects applied to two penguin images. 


□ ^untitled.mouii^S 



figure 2: Ihe explode effect applied to two images 


Figure 1: The horizontal ham zig-zag wipe effect applied to 
two video tracks 


Tim Monroe's lizards have perfected the color-tint effect, changing from green to brown (and vice versa) at their whim. In his day job, Tim is a 
member of the QuickTime engineering team. You can contact liim at monroeOapple com. 
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□ ^untitled.inoM^i^ 



Figure J: The push effect applied to tuKf images 

QuickTime :iLso includes a very nice cross-fade or dissokfe 
transition (which produces a smooth alplia blending from tlie 
first image to the second) and a nifty film noise rilter that makes 
a video track look like old, faded, dusty, and scratched film. 
Figure 4 shows a frame of a movie with the film noise effect. 


□ ^ untitled.mou 



► ' )( il !► 4 


Figure 4* 72?^ Jtlm noise effect applied to a movie frame 


There are several video effects tliat operate on no source 
images or video tracks at all, called effects generators. For 
instance, we c^n use theeffect to generate a real-looking fire 
(see Figure 5), and we can use the cloud effect to generate a 
wind-pushed, moving cloud. With generators, we will usually 
want to composite the effect onto some other image or video 
track. Figure 6 shows the fire effect composited onto the 
penguin image. (Ouch, that’s gotta hurt!) 



Figure 5* The fire effect in a mome 


□ s penguin.moM = S 



Figure 6: The fire effect composited onto an image 

The data describing an effect is stored in a video track, and 
the actual effect itself Ls generated in real time as the movie is 
played. These effects use extremely little data to achieve the 
desired visual output. For instance, a video track diat specifies 
the fire effect is only alxjut 60 bytes in size; when the track is 
played, QuickTime generates a real-time, non-repeating, 
dynamic fire image. 
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Generators, filters, and transitions are implemented in the 
general QuickTime architecture as image decompressor 
components (of type decompressorComponentTypB). One thing 
this means is that we can reference a specific effect by providing 
a four-character code, which is an image decompressor 
component subtype. Here are a few of the available effects types: 


enmn I 

kWaterRipp1eCode c Typ e 

kFireCodecType 

kP i 1 ihNq i s e I mageFll t G r Typ e 

kWipeTransltionType 

klrisTransitionType 

kRadlalTransitlonType 

kMatrixTtansitlonTypG 

kCrossFadeTransitlonType 

kPu s hT tansitio nType 


= FOUR_CHAR_CODE('rlpl'], 
“ FOUR_CHAR_CODECflre'), 
= F0tlR_CHAR_C0DE (‘ f mns *), 

= FOUR„CHAR_CODE('smpt'}, 
“ F0UR_CHAR_C0DECsiiip2'), 
= FOtJR^GHAR_CODE (‘ stiip3 ^) * 
= FOUR„CHAR_CODE {' sinp4 ’} * 
= FOUR^CHAR_CODE [' delv'), 

“ FOUR_CHAR_CODE C'push') 


Anotl^er tiling this means is that we can use QuickTime 
video effects anywhere we might use a decompressor, not only 
in connection with QuickTime movies. We can just as easily 
apply a transition between two arbitrary images (perhaps 
contained in two offscreen graphics wodds). Fve seen this 
capability used in applications that support QuickTime video 
effects as iransitioas between QuickTime VR ncxles. The default 
behavior of QuickTime VR Ls simply to jump from one node to 
the next. It's much nicer to render some video effect, say a nice 
smooth dissolve, when moving from node to node. 

In this article and the next, we’re going to work with 
QuickTime video effects. Well see how to create the fire movie 
shown in Figure 5 and how to apply a filler to a video track or 
image. We ll also see how to display and manage the effects 
parameters dialog box, which allows the user to select an effect 
and modify the parameters of that effect. Finally, we'll see how 
to apply an effect to only part of an existing movie and how to 
use effects as sources of sprite images. 

Our sample application in tliese two articles is called 
QTEffects; its Test menu is shown in Figure 7. 


Test 


Make Fire Mouie... 

Make Fade-In Mouie... 

362 

Rdd Film Noise To Mouie 

365 

Rdd Film Noise to Image 

364 

Make Effect Mouie... 

365 

Standalone Mouie 

366 

Referenced Mouie 

367 

1 Rdd Effect Segment to Mouie 9S8 [ 

1 Make Sprite Effect Mouie... 

369 1 


Figure 7: The Test menu ofQTEffecis, 
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In this article, well see how to handle aU these menu items 
except for the fourth (which happens to be grayed out) and the 
final two. Well postpone consideration of those three items to 
our next article. 

QuickTime Video Effects m Movies 

It’s extremely easy to add a video effect to a QuickTime 
movie. In the simplest case^ where the effect lasts for the 
entire length of the movie, we just add an effects track to the 
movie. An effects truck is a video track (of type 
VideoMedtaType) whose media data is an effect description. 
An effect description is an atom container that indicates 
which effect to perform and which parameters, if any, to use 
when rendering the effect. The effect description also 
indicates which other tracks in the movie are to be used as 
the input sources for the effect. These are called the effect 
source tracks (or effect sources). A transition needs two 
source tracks; a filter needs one source track; a generator 
needs no source tracks. Figure 8 illustrates the general 
structure of the fire movie shown in Figure 5. 


As well see in greater detail later, we need to connect 
an effects track to its source tracks by setting up track 
references from the effects track to the source tracks. These 
references tell QuickTime where to get the data for the 
effects track. We also need to configure the effects track's 
input map, so that the effects track knows how to interpret 
the data it receives from the source tracks. Hie source tracks 
operate as modifier tracks, whose data is not presented 
directly to the user; rather, their data is used as input for the 
effects track. This is important, particularly when we want to 
apply an effect to only part of a source track. You might 
think that we could just construct an effects track with the 
appropriate start time and duration, as shown in Figure 10, 
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Figure 10: A filter applied to pari of a video truck (wrong) 



Figure 8: The structure of a zero-source effect movie 

And Figure 9 illustrates the general .structure of a movie that 
contains a two-source effect (perhaps the zig-zag transition 
shown in Figure 1). 
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figure 9: The structure of a two-source effect movie 


The source tracks for a video effect can be any tracks 
that have the visual media characteristic, including video 
tracks, sprite tracks, text tracks, and others. In particular, 
because an effects track is a video track, it too can be a 
source track for another effects track. This allows us to stack 
effects, so that the output of one effect is used as input for 
another effect. For example, we could set up a crossTade 
transition from one video track to another, and then apply a 
film noise filter to the resulting images. Keep in mind, 
however, that some effects can use a significant amount of 
CPU power, so that stacking effects may result in movies that 
do not play smoothly in real time on slower machines. 


But this won’t work, since once we’ve created a track 
reference from the effects track to the video track and .set the 
effects track’s input map appropriately, the video track will 
send all of its data to the effects track, not just the data In 
the track segment that overlaps the effects track. To apply an 
effect to a part of a track, we can create another track that 
has the de.sired start time and duration and that references 
data in the video track. Then we use this new track segment 
as the source track for the effect, as shown in Figure 11. The 
new track segment doesn’t contain a copy of the media data; 
instead, it contains references to the media data that already 
exi.sts in the video track. So we don't increase the size of a 
movie file very much at all when we add effects to it. 


pnPDDnnaDcnanQDaoDDDnQDDDDDDaDnDODD 
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Figure II: A filter applied to pan of a video track 


All three of the tracks shown in Figure 11 are enabled; to 
prevent the original video track from covering up the effects 
track, we need to make sure that the effects track has a lower 
track layer than the video track. Well see exactly how to do 
this in the next article, when we discuss applying effects to 
track segments. 

It’s worth mentioning that the QuickTime video effects 
architecture was originally designed to render effects in real 
time using software effects components (which, as weVe 
seen, are image decompressor components). Recently, 
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QuickTime 5 added support for hardware acceleration of 
effects rendering. This acceleration is used only when the 
user’s machine has the appropriate hardware installed, and it 
occurs automatically (without any intervention by the effects 
movie creator or the playback application). 

It’s also worth mentioning that a video effect can have 
more than two sources. QuickTime 5 introduced a three- 
source effect, the traveling matte effect, tn these articles, 
we’ll always work with two or fewer sources, but our code 
can in fact handle up to three. 

Effects Utiuties 

Before we begin creating effects movies, let’s take a brief 
moment to define a couple of functioas that will be useful 
throughout our effects cade. 

Creating a Sample Etecription 

When w^e build an effects track, we need to pass 
AddMediaSample an image description that provides information 
about the effect. In the past, weVe always created sample 
descriptions and image descriptions by calling NewHandleClear 
and then setting the fields of the structure appropriately. When 
we are working witli effects, however, we should use the 
function MakelmageDescriptionForEffect. which allocates a handle 
to an image description and fills in some of its fields; it also 
attaches an image description extension to the end of tlie image 
description. This extension indicates that that image description 
applie.s to an effetn. For most purposes this extension is ignored, 
but it's necessary when we want to create stacked effects. 

MakelmageDescriptionForEffect was inmxlucxxl in QuickTime 
4.0; if we want our code to mn also under versions 3.x, we on set 
the USES_MAKE„IMAGE_DESC_FOR_EFFECT compiler Rag to 0. 
Listing 1 shows our definition of EffectsUtils_MakeSampleDescription, 
which we’ll call quite a few times in QTEffects to create an image 
description lor an effea. 

Listing 1: Creating a sample description for an effect 

Effet:tsl]iib_MakeS;inipleDescription 

ImageDescriptionHandle EffectsDtils_M0keSampleDescription 
(OSType theEffectType, short theWldth, short 
theHeight) 

I 

IraageDeacriptionHandle inySampieDesc * MULL: 

(/if USES_MAKE_rMAGE_DESC_FOR_EFFECT 

OSEct inyErr ” noErr: 

// create a new sample descrtptian 

inyErr = MakelmageDescriptionForEffectCtheEffectType, 
imySampleDeac): 

if (myErr != noErr] 
return(NULL): 

//else 

// create a new sample description 

mySampleDesc = (rmageDescxiptionHandle) 

Mev/HandleClear(siKeof ClmageUescriptlon) ] : 

If (tnySampleDesc = NULL) 
returTi(NULL): 


// fill in the fields of the sanipie description 
(“tnySampleDesc) .cType ^ theEffectType: 

(* ^mySampleDesc) .idSize = sizeof tlmageDescription); 

(••mySampleDesc).hRes = 72L « 16: 

E* *tiiySfljnpleDeBc) , vRes ” 72L << Id: 

E * *mySampleDesc).frameCount = 1: 

(* •raySaiapleDesc) .depth “ 0; 

E“tnySainpleDesc) .clutID = '1: 

#endif 

E^*mySanjpleDesc).vendor ” kAppieHanufacturer; 

E*‘mySaiapleDefic)ttemporalQuallty ^ eodecNormalQuallty; 

(*'mySampleDesc).epatialQuality = codecNormalQuality; 
(**iuySampleDesc) .width “ theWidth; 

(* * tnyS amp leDe s c). h e i ght = theHel ght: 

return(mySampleresc): 

I 

Notice that we need to set a few fields of the image 
description even if we call MakelmageDescriptionForEffect. 

Creating an Effect Description 

It’s also useful to define a utility function to build an effea 
description. As we’ve learned, an effed description is an atom 
container that specifies an effea and its .sources. listing 2 .shows the 
definition of our utility EffectsUtils_GreateEffedDescription. The 
essential step is to add an atom of type kParameteiWhatName and ID 
kParameterWhatlD whose data is ilie four-character code for tlie 
desired effea. 


Listing 2: Creating an effect description 


l^fectsUtjis_t;rcateEffcciu«ict1ptii>n 

QTAtomContainer Effect 0 Utlls_CreateEffectDescription 
(OEType theEffectType, OSType theSourceNamel. 

OSType theSourceName^, OSType theSourceNameS) 
t 

QTA torn Container tnyBffectDeec ^ NULL: 

OSType myType = EndiantJ32_HtoBttheEffectType): 

OSErr myErr “ tioErr: 

// create a new, empty efrect de^icriptian 
myErr ” QTNevAtoaGontaltier(fiiiijyEffectDese); 
if (myErr noErr) 
goto bail: 

// create the effect ID atom 

myErr = QTInaertChild EinyEffectOesc, kParentAtomlsContainer, 
kParameterWhatNaine, kParameterWhatlD, 0, 
sizeof(myType). imyType, NULL); 
if (myErr != noErr) 
goto bail; 

// add the first source 

if (theSourceNainel 1= kSourceNoneName) 1 
tnytype “ EridlanU32_NtoB (theSoiirceNainel) ; 
myErr ^ QTInsertChlld(aiyEffectDeac* 

kParentAtotnlsContainer* kEffectSourceNanie, 1, 0, 
sizeof EmyType), SimyType, NULL): 

If (myErr [= noErr) 
goto bail: 

1 

// add the second source 

if CtheSciurceName2 != kSourceNoneNatne) I 
myType “ EndianU32_NtoB(th6SaurceName2) ; 
myErr = QTInsertChild{myEffectDssc. 

kParentAtomlsContainer* kEffectSourceName* 2, 0, 
sizeof (myType), feiiiyType, NULL); 
if (myErr \= noErr) 
goto bail: 

J 
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// add the third source 

if (tlieSoiirceNaiiie3 J= kSourcGNoneName) ] 
myType = EndianU32_NtoB (theSourceNameS) : 
myErr = CiTInsertChild(iiiyEffectDesc, 

kParentAtoralsContainer, kEffectSourceName3^ 0, 
slzGof (tnyType) T &myType^ NULL); 


bail: 

return(myEffectDesc); 


EffectsUtils_C reate Effect Description builds an effect 
description with up to three iiotirce name atoms^ of type 
kEffectSourceName, Tlie data in these atoms is a stmrce name, of 
type OSType, Source names are used to link the source tracks to 
the effects track, These names are arbitraiy, but Apple 
recommends using names of the form 'srcAT, where X is an 
uppercase letter. In the file EffectsUtiIities.h, we define these 
constants for our source names: 


/Mefine kSourceOneHame 
/Mefine kSourceTwciNatne 
/Mefine kSourceThreeNaine 
/Mefina kSoUrceHoneName 


F0aR_CHAR_C0DE('s rcA M 
FOUR^CHAR^COBE(^ s rcB') 
F0UR^CHAR_C0DE{^srcCM 

F(}lJR_CHAR_CODE (^ srciE*) 


Wlien we call EffectsUttls^CreateEffectDescription, well pass the 
constant kSourcsNoneName fur any unused sources. 


Getting an Effect Type 

Sometimes we might get our hands on an effect 
description and need to know what kind of effect it 
de.scribes. We can get this information by inspecting the data 
of the atom of type kParameterWhatMame and ID 
kParameterWhatlD that's inside that effect description. The 
function EffectsUti!s_GetTypeFromEffectDe$cription defined in 
Listing 3 accomplishes this. 


if (mjEffectTypeSlze 1= sizeof(OSType)) [ 
myErr = paramErr: 
goto bail: 


'^tbeEffectType = * (OSType OniyEffectTypePtr: 
*theEffectType = EndiaEU32_BtotJ(*theEffectType) ; 

myErr = QTUnIockConta.iner (tbeEffectDesc) ; 
t 

bail: 

return[myErr]: 

1 


Notice that we call QTLockContainet on the effect 
description, even though it isn’t strictly necessary here. As 
we learned in a previous article, QTGetAtomDataPtr returns a 
pointer to the actual leaf atom data. We need to call 
QTLockContainer only when we make calls that might move 
memory; in this case, weTe just reading a few bytes into a 
local variable, and this operation will not cause any memory 
movement. The calls to QTLockContainer and 
QTUnlockContainer are fairly lightweight, so we’ll make them 
anyway. 


Generators 

Let’s begin our hands-on work with QuickTime video 
effects by building a movie that uses a generator, or zero- 
source effect. In [his case, we’ll build the fire movie shown 
earlier in Figure 3. This movie has only one track, which is 
an effects track and which has only one media sample. We’ll 
set the dimensions of the effects track and its duration using 
some hard-coded values: 

/Mefine kDefaultTrackWidth 160 

//define kDefaultTrackHeigbt 120 

//define kEffectMovleDuration (10 kOneSecond) 


Listing 3; Getting the type of an effect 


EffccL^t llils_C ret'iy peFramEffect Dt scription 

OSErr EffectsUtils_GetTypeFrc'TnEffectDescriptlon 

(QTAtOJuContainer theEff ectDesc, OSType the Effect Type) 

f 

QTAtom inyEffectAtQm = 0: 

long myEffectTypeSize * 0: 

Ptr myEffectTypePtr - NULL; 

OSErr myErr = noErr; 

if ({theEffectBesc = NULL) || (tbeEffectType NULL}) 
return[paramErr]: 

myEffectAtom = QrFitidChildByIndex[theEffectDesc . 

kParentAtomIsContainer, kParameterWiatNaiDG, 
kParameterWbatlD, NUT.L): 
if [myEffectAtom != 0) ( 

myErr = QTLockContainer(thoEffectDesc): 
if (myErr !- noErr) 
goto ball: 

myErr = QTGetAtomDataPtr (theEffectDe.9c < myEff ect Atom. 

6imyEf fectType Size, ^myEff ectTypePtr) ; 
if (myErr 1= noErr) 
goto bail; 


We create the new movie file by calling CreateMovieFila, and 
then we create a new^ effects track and media like this: 

tnyEffectTrack - NewMovieTrack (myMovie , 
IntToFixod(kDefaultTr3ckWidthi . 

IntToFixed(kJDefaultTrackHelght) , kNoVolame) : 

inyEffectMedis - NewTrackMedla(Ti3yEffectTrackH VldeoMedlaType, 
kOne 3 ec o nd. NULL, 0); 


Now we are ready to use tlie utility functions we defined in 
the previous secticm. We create the .sample description and the 
effect description: 

mySamplsDesc “ EffectsUtil3_HakeUampleDeacription 
(kEireCodecType, kDefaultTrackWidth, 
kDefaultTrackHel^ht]: 

myEffECtDeac = EffeetaUtils_CrGateEffectDezcrlption 

(kFireCodecType, kSourceNoneName. kSourceNoneNamet 
kSourceNoneNanae) : 

The fire effect takes no sources, so we pass the constant 
kSourceNoneName for all three source name parameters. 
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Now we are essentially done; we add the effect description 
as a media sample using the usual media-editing song-and- 
dance (BeginMediaEdits, AddMediaSample, EndMediaEdte, and 
InsertMedialntoTrack), The key step is the call to 
AddMediaSample: 

:QyErr = AddMediaSajnplefinyEffectUedia, myEffectDesc, 0^ 

GetHandleSize(myEffectDesc), kEffectMoyieDuration, 
(Sa!iipleDescrlptionHandle)iQySampleDesi:i. 1, 0, 
&ttiySainpleTiiiie) ; 


It’s really just tliat easy to create a zero-source effeds movie. 
Listing 4 show s the complete definition of QTEffecls_MakeFireMovie, 
w^hich we call in response to tlie '‘Make Fire Movie.,menu item. 

Listing 4: Creating a zero-source effects movie 

QTEffccts_JVLikcFircMoviL- 


void QTEffects_MakeFireMovie (void) 


FESpec inyFile; 

Boolean mylsSelected = false; 

Boolean mylsReplncing = false; 

StringPtr rayPirompt - 

ClTUtiln_ConvertCToPascaiString(kEffectsEaveMoviePrompt): 
StringPtr myFiletlaiDe " 

QTUtiIs^ConvertCToPascalString(kEffeetsFiraMovieFileName); 
Movie myHovie - NULL; 

short myMovieRefNuni = klnvalidFileReffiuiii; 

short myRealD = niovielnDataForkResID; 

Track myEffectTrack = NULL: 

Media myEffectMedia = NULL: 

QTAtomContainer myEffectDesc “ NULL; 
ImageUescriptionHandle 

nySampleDesc = NULL; 

TimeValue mySarapleTime - 0: 

long myFlags = createMovieFileDeleteCurFile 

I oreateMovieFileDontCreateResFile; 
OSType myType = FOUR_CHAR_CODE(*none'); 

OEErr myErr ™ noErr: 


// a,sk the user for ihc name of the new movie tile 
QTFrame_PutFile(myPrQiiipt, niyFileName» imyFile» 
SmyIsSelacted, imylsReplacing); 
if [fraylsSelected) 

goto hall: //ded with U-sercancelling 


// create a movie file for the deistinatioii movie 

myErr “ CreateMovieFile(SniyFile, sigMoviePIayer. 

smSyatemEcrlpt p myFlags , &myHovleRefNuEt]. ^rnyMovie) ; 
if (myErr != noErrJ 
goto bail: 


// .select the''no controller^ movie contmler 
myType = EndianU32„NtoB(myType); 
Setl]aerDataItem{GetHovieUserData(myMovie)p ^myType. 

sizeof(myType). kUserDataMovieControllerTypep 1): 

// create the effects track 

myEffectTrack = NewMovieTrack(myHovie^ 
IntToFixedfkOefaultTtackWidth). 
IntToFixed(kDefaultTrackHeight), kNoVoIume): 
if (myEffectTrack == NULL) 
goto bail: 


myEffectMedia = MewTrackMedia(myEffectTrack, 
VideoMediaTypsp kOneSecondp HULL. 0); 
if {myEffectMedia = NULL) 
goto ball: 

// create the sample description 

JnySampleDesc - EffectsUtils_MakeEampleCGEciription 
(kFireCodecType, kDefaultTrackWidth, 
kUefatiltTrackHeight) ; 
if (rnySampleDesc = NULL) 
goto bail: 


// create the effect description 

myEffeetDese = EffectsUtils_CreateEffectDescription 

{kFireCodacTypep kSotitceNoneNaiDe + kSourceNonoNamep 
kSourceNoneName): 
if (myEffeetDese = NULL) 
goto bail: 

// add the effect description as a sample to the effects track media 
myErr = BegiiiMediaEdits(myEffectMedia); 
if (myErr 1= noErr) 
goto bail; 

myErr = AddHediaSample(myEffectMedia, myEffectDescp Op 

GetHandleSize(myEffoetDeso)p kEffectMovieDuration, 
(SampleDescriptionHandle)mySafflpleDescp 1, 0, 

Siiny Sample Time): 
if (myErr 1= noErr) 
goto bail: 

myErr = EndMediaEditsfmyEffentMedia); 
if (myErr 1= noErr) 
goto bail: 

myErr = InsertMedialntoTrack(myEffeetTrackp Op 

mySamplGTiine p kEf f ectHovieDuration p fixedl) ; 
if (myErr noErr) 
goto bail: 

AddMovieResource(myHovie, myMovieRefNum, ^myResIDp HULL): 
bail; 

if (fflyMovieRefNum !“ klnvalidFileRsfNum) 

GlO'SeMovieFile (myMovieRefNum): 

if (myHovie i- NULL) 

DisposeHovie(myHovie) : 

if (myEffeetDese !- NULL) 

QTDisposeAtomContainer(myEffectDesc): 

if (mySampleDesc!= NULL) 

DisposeHandle[(Handle}mySamplaDesc): 

freelmyPrompt): 
freefniyFileNaine}; 

return; 


With the fire effect, the duratkjn is fairly arbitrary. Any non¬ 
zero duration would prcxluce the same visual output. 

Filters 

It’s just about as easy to add a filter to a video track in an 
existing movie — for in.stance, to handle the “Add Film Noise To 
Movie” menu item. We add an effects track, whose media data 
consists of an effect description. This time, however, we need to 
specify a source name in the effect description. Well call our 
utility Effects Uti!s_C re ate Effect Description like this, passing 
kSourceOneName as the first source name parameter: 

myEffeetDese = EffectsUtils_CreateEffectEescripticin 
(kFiImNoiselmageFilterType, kSourceOneName, 
kSourceNoneName, kSourceNoneName): 


We also need to create an input map for the effects track, 
which specifies which track is to be used -as the effect source. 
Listing 5 shows the code we use to create, configure, and set the 
input map. 
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Listing 5: Creating an input map for an effects track 


QTEffects_AddFilmNdseTt>Mcivic 

// create the input map and add references for the first effects track 
myErr = QTKewAtomCoatainer [^imylnputHap) * 
if (myErr 1“ naErr) 
goto bail: 

myErr ” EffectaUtils_AddTrackReferenceToInputMap 

(myInputMap. myXrack. myStcTrack. kSonrceOnel^ame) ; 
if {myErr noErr) 
goto bail: 

// add the input map to the effects track 

inyErr “ SetKediarnputMap(inyMedia, mylnputMap) i 

An input map for an effects track is an atom container 
that holds one atom of type kTrackModilierlnput for each 
source track that is sending data to the effects track. The ID 
of each such atom must be set to the reference index 
returned by AddTrackReference when the track reference 
between the effects track and that source track is created. 
Each atom of type kTrackModifierlnput must contain at least 
two child atoms. One of these children is of type 
kTrackModifierType and specifies the kind of data the target 
track is going to receive from the source track; in the case of 
an effects tracks the type of the modifier track input is 
kTrackM odifierType I mage. The second child atom in an input 
map entry atom specifies the name of the source track and is 
of type kEffectDataSourceType; the data in this atom is of type 
OSType. Figure 12 shows the structure {)f the input map 
well use to add the film noise filter to a video track. 



Figure 12: The structure of an input map far an effects track 

Listing 6 shows our definition of the 
EffectsUtils^AddTrackReferenceToinputMap function, which we 
use to add the appropriate children to an existing Input map 
for an effects track. 


Listing 6: Adding track references to an input map 

Mcct5LitiJs_AddTrackReferenccTolnp ut Map 

OSE rt Effect aUt i 1 s_AddTra c kRef e r euc eTo I tip utMa p 

CQTAtoniContaltier thelnputMap. Track theTrack. 

Track theSrcTrack, OSType tbeSreffame) 

I 

QTAtom iny Input At ora: 

long rayRefIndex: 

OSType myType; 

OSErr rayErr = noErr: 

DiyErr “ AddTrackReference(theTrack. theSrcTrack. 

kTrackReferenceModifier, fiimyRefIndex): 
if (myErr 1= noErr) 
goto ball; 

// add a reference atom to the input map 

ciyErr = QTInsettChlld(thelnputMap, kParentAtomlsContainer* 
kTrackModiflerlnpUt. myKefIndex, 0. 0, MLL, 
&myTnptitAtotn); 
if (inyErr noErr] 
goto bail; 

// ad<l two child atoms to the parent reference atom 

myType = EndianU32_NtoB(kTrackModifierTypeIraage) : 

myErr = QTlnsertChild(thelnputMap, myInputAtom, 

kTrackModifierType, 1, 0, sliieof (rayType) , SrayType, 
MULE): 

if (myErt 1= noErt) 
goto bail; 

myType = EiidlanU32_HtoB CtheSrcName); 

myErr ” QTinaertCh±ld(theIiiputMap, mylnputAtom, 

kEffectDataSourceType, 1. 0, slzeof(rayType), 

^myType, 

NULL); 

bail: 

return (myErr) ; 

] 

If EffectsUtils_AddTrackReferenceTolnputMap seems familiar, 
that's because we've already bumped into similar functions (for 
instance, when we worked with sprite image overrides in *‘An 
Extremely Goofy Movie" in Maclech, April 2001). 

TRANSmONS 

Adding a transition to a movie witli two video tracks is really 
no more complicated dian adding a filter to a movie with one 
video track. We pass kSourceTwoName as the second source name 
parameter when calling EffectsUtils_CreateEffectDescfiption, and 
we can Effectsytils_AcknfackReferenGeTolnputMap a second time, to 
create a track reference Ix^iween the effects track and die second 
source video track. For fun, let's see how' to recreate our 
appearing“penguin movie using QuickTime video effects. Well 
also take tills oppcjitunity to play a ilttJe more with our favorite 
Image CompressicMi Manager functioas GetMaxCompressionSize 
and Compressimage. 

Given what we've learned so far, ail we really need to do is 
create two video tracks to serve as the source tracks for a cross- 
fade transition. The first video track is an all-white frame that 
lasts for the duration of the movie; the second video track is the 
fully-opaque penguin picture, also lasting for the duration of the 
movie. As always, we’ll set the duration of the movie to 10 
seconds, this time using the constant kEffectMovie Du ration. Then 
we'D add the effects track to the movie, specifying a cross-fade 
from the first source track to die second. 
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The rwo images that we’ll use to create our video tracks are 
stored in our application's resource fork, in two PICT’ resources 
with these IDs: 

^define kWhiteRectlD 129 

kPenguinPictlD 12S 


vSo w e need to read each image and create a video track of die 
desired lengtli. Well split our work into two parts. First well write 
a utility, EffectsUtils_GetPictRssourceAsGWorld, that reads a PICT 
resource and draws it into an offscreen graphics world. Then well 
write another utilin^ EffectsUtils_AddVideoTrackFromGWoiid, that 
creates a video track from the image in an offscreen graphics 
world. Once weVe got these two utilities, we can create the two 
video tracks using the code shown in Listing 7. 


Listing 7: Creating two video tracks from two 'PICT 
resources 


Q'rEftt:LL!i_Ma.ki:i’CnguinMt>vit: 

myEri: - EffectsUtils^GetPictResourceAsGWorld (kWli.iTeRectrD, 

kPengainTrackVidth, kPenguinTrackHeight, 0, ^iinyGWl); 
if [iiiyErr != noErr) 
goto 13311: 

mjErr ~ Eff ect!3Utils_GetPictReEourcieAsGW'OrId (kPenguinPictID, 
kPengulnTrackWidth* kPenguinTrackHeight, 0. &myGW2]; 
if (myEtr 1= noErr) 
goto bail: 

iriyErc - Effe£tsUtils_AddVideoTrackFroniGWorld(£(TiiyHovieH myGWl. 
^mySrclTrack. 0 , kEffectHovieDoration► 
kPenguioTrackWidth. kPenguioTrackHeight): 
if (myErr f= noErr) 
goto bail: 


To create an offscreen graphics w^orld that holds the 
image stored in a PICT' resource, we get the picture data 
from the resource (by calling GetPicture), create an offscreen 
graphics world of the required size (by calling 
QTNewGWorld), and then draw the picture data into that new 
graphics world (by calling DrawPicture), Before drawing into 
our graphics world, however, we need to call LockPixels to 
lock the offscreen pixel image. Listing 8 shows our definition 
of EffectsUtiis^GetPictResourceAsGWorld. 

Listing 8: Creating a graphics world from a ‘PICT' 
resource 


Effe€tsUtiJs_GetKctResoiJtTeAiiGW<>[ld 


OSErr EffectsUtlls_GetPictResourceAsGWorld (short theResID, 
short theWidtb. short theHeight, short theEepth. 
GWorldPtr "theGWl 
I 


PicHandle 

PixMapHandle 

CGrafFtr 

GDHandie 

Rect 

OSErr 


myHandle ” NULL; 
myPixMap “ NULL: 
mySavedPortI 
mySavedDevice: 
myRect: 

myErr = noErr: 


// gel die curreni drawing envLronmeni 
GetGWorld{fiiutySavedPort, fitmySavedDevice) : 

// fc:id Lhc specified PICT' resource from the applicdUon's resource ftJc 
inyHandle - GetPlcture(theRssID) ; 
if [myHandle = NULL) f 
myErr ” ResErrorO; 

If (myErr ™ noErr) 
myErr = resNotFound: 
goto ball: 


myErr = Effectslltil£,_AddVideoTrackFromGWorld(fiitnyHovie, myGW2H 
&mySrc2Track, Q, kEffectMovieDuration. 
kPengulnTrackWidth, kPenguinTrackHeight); 


// set the si3te of the (iWurtd 

MacSetRect(^myRect. 0. 0. theVidth. theHeight): 
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// allocate a new G World 

myErr = QTKewGWorld{theGW< theDepth* StinyRect* NULL, NULL* 
klCMTeinpTheoAppMeiDory) ; 
if (myErr 1= noErr) 
goto bail: 

SetGWorld(*theGW, NULL); 


If (theSourceTrack = NULL) 
goto bail; 

myMedia = HewTrackMadia(*theSourceTrack, VideoMedlaTypa, 
kVideoTrackTlmeScale* NULL. 0): 
if (inyHedia = NULL) 
goto bail; 


// get a handle to the offscreen pixel image and lock it 
myPixMap = GetGWorldPixNap('^theGW) ; 
LockPixela (tnyPixMap) : 

BraseRect {fiiinyRect) ; 

D r awPic tu r e(myHandIe * ^myReat}; 

if {myPixHap != NULL) 

UniockPlxela(myPixMap); 

bail; 

// restore the previous port and device 
SetGWorld(mySavedPort. mySavedUevice): 


// get die rectangle for the movie 
G E tMo VieB ox(* theMovie. imyRect); 

// begin editing the new track 
myErr = BeginMadiaEdits(myMedia): 
if [myErr 1“ noErr) 
goto bail; 

// create a new GWorld; we di^ the picture into this GWodd and then compress it 
// (note that we are creating a picitire with the maximum bit depth) 
myErr = NewGWorld(&myGWorld, 32, SfiByRect. NULL, NULL* OL); 
if (myErr != noErr) 
goto bail; 


if (myHandle 1= NULL) 

ReleaseResource {(Handle) myHandie) : 

return[myErr]: 

I 

Now we want to create a video track in a movie that lasts 
for a specified duration and whose data is the image 
contained in an offscreen graphics world. Listing 9 shows the 
complete definition of Effec1sUtils_AddVideoTrackFromGWorld, 
This function is a tad long* since we need to create a new 
track and add a media sample to it; we also need to call 
GetMaxCompressionSize and Compressimage to compress the 
data in the original graphics world to reduce the size of the 
resulting new movie track. Notice that we return the track 
identifier to the caller through the theSourceTrack parameter, 
(For more details on calling GetMaxCompressionSize and 
Compressimage, see ''Making Movies'* in MacT(^cb^]\im 2000.) 

Listing 9; Creating a video track from a graphics world 

EffcctHlftjls_AddVitleoTmckfromG World 


mySrePixMap = UetGWorldFixMap(theGW) ; 
myDstPlxMap “ GetGWorldPixMap(myGWotld) : 
LockPixels(iiiyDstPixMap); 

// create a new image description; Compressimage will fill in the fields of this 
stmcitire 

mySampleDesc = [I]nageDescriptionHandle)NewHandie(4); 

SetGWorld(myGWorId* NULL); 

#if TARGET_.OS_MAC 

GetPortEoundsitheGW, &iiiyRect2) ; 

GetFortBpundE(myOWorld, ^myRectS): 
ilendif 

#if TARGET„OS_WIN32 

rayRect2 = theGW >poj:tRe{:Lt; 
myRect3 = myGWorld->portRGCt; 

#endif 

// copy the image fmm the s|>eciffed GWorld into the new GWorld 
GapyBits( [BitMapPtr) *raySrcPixMap, (BitNapPtr) ‘myDstPixMap, 
&jiiyRect2, &myRect3, sreCopy, NULL): 

// restore the original port and device 
SetGWorld [mySavedPort, laySavedGDevice) ; 

myErr “ GetMaxCompressionSize(myDstPlxMap, ^myRect, 0. 
codecNorinalQuality* kJPEGCodecType, anyCodec* 
^tnySize): 

if [inyErr !“ noErr) 
goto bail; 


OSErr EffectEtftlls_AddVideaTrackFroii3GWorld [Movie *theMovle, 
GWorldPtr theGW, Track 'theSourceTrack. 
long theStartTime* TlmeValue theDuration* 
short theWidtb, short theHeight) 

I 


Media myMedia; 

ImageDeacriptionHandle 

mySainpleDese = NULL; 
Rect myRect; 

Rect rayReetZ: 

Rect tnyRectl; 

long mySize; 

Handle myData - NULL; 

Ptr myDataPtr ” NULL; 

GWorldPtr myGWorld = NULL; 

CGrafPtr mySavedPort = NULL; 

GDHandle mySavedGDevice - NULL; 

PicHandle myHandle = NULL; 

PixMapHandle mySrcPlxMap = NULL; 
PlxMapHandle myDstPixMap = NULL; 
OSErr myErr = noErr; 


myData = NewHandle(mySlze) ; 

If [myData “ NULL) 
goto ball; 

HLocktll (myData) : 

#lf TARGET_CPU^68K 

iDyUataPtr = StripAddress [’‘myData) ; 
ifelse 

myUataPtr ^ 'myData; 

#endlf 

myErr = Conipresslmage (myDstPlxMap * toyRect* 

codecNorinalQuallty * kJPEGCodecType, rdySampleDesc , 
myDataPtr): 
if (myErr 1= noErr) 
goto ball: 

myErr = AddMediaSample(myMedia, myData. 0, 

(' 'laySampleDesc) * dataSize * theDuratlon, 
(SaiiipleDeacriptlonHandle)mySampleDesc, 1* 0, NULL): 
if [rayErr 1= noErr] 
goto bail; 


myErr = EndMediaEdits(myMedia); 
if (myErr f= noBre) 
goto ball; 

'theSourceTrack = NewMovieTrack{*theMovie. 

IntToFixed(theWidth). IntToFlxed(theHeight)* 
kHoVolume); 


// get the current port and device 

GetGWorld{^raySavedPort, SriaySavedCDevice) : 


li f’fTpatf* a viftpn Imf't in thp 
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myErr = InsertMediaIntoTrack(*theSourceTrack, theStartTime. 

0, GetMediaBuration(iiiyMedia) * f lxedl)i 

bail: 

// restore the original pon and device 

SetGWorld{iriySavedPort . mySavedGDevlce): 

if (myData t- NUU) ( 

HUnlDckCmyData]; 

DisposeHandle(inyData) ; 

1 

if (mySamplEDeac]= NULL) 

DlsposeHaadle {(Handle}mySatnpleDeac:); 

if (myDstPixMap != NULL) 

UnlockPixelsCmyDstPixWap): 

if (myGWorld != NULL) 

DisposeGWorld(myCWorld); 

reti]rn(myErr): 

I 

See the file QTEffects.c for the complete listing of 
QTEtfects_MakePenguinMovie, which we call in response to 
the ‘'Make Fade-In Movie../ menu item. It's really just a 
longer version of QTEffects_MakeFireMov]e {Listing 4) that 
incorporates the extra code in Listing 7. 

Before we move on, it’s worth reflecting on the fact that 
the movie created by QTEffects_MakePenguinMovie is now the 
fourth version of our penguin movie. We first created an 
appearing-penguin movie in '‘Making Movies’" (cited earlier), 
w^here we built a video track with 100 frames, each frame 
having slightly more opacity than the previous. The total size 
of the movie file w^as about 470 kilobytes. In “A Goofy 
Movie” (March 2001), we created a second version of the 
penguin movie, using a sprite image in a key frame with zero 
opacity and 99 override frames that gradually increased the 
level of opacity of the sprite image. This version of the 
penguin movie fOe was only about 36 kilobytes. In the very 
next article (*An Extremely Goofy Movie”, April 2001), we 
reworked that sprite version using a tween track to change 
the graphics mode of the penguin sprite image. The total size 
of that version was about 28 kilobytes. Finally, in this article, 
we’ve created a movie file that uses the cross-fade transition 
to blend from a totally white frame to the penguin image; 
this version is only about 10 kilobytes (most of w^hich is 
occupied by the compressed penguin image). 

One moral of this story is obvious: there is more than 
one way, using QuickTime, to skin a cat (or fade in a 
penguin). The first version uses a single video track. The 
second version uses a single sprite track. The third version 
uses a sprite track and a tween track. This fourth version uses 
two video tracks (the sources) and an effects track. None of 
these versions is inherently any better or worse than any of 
the others (though it's hard not to choke on the beefy size of 
the first version). Which of them we employ for a specific 
purpose depends on various factors. For instance, if we want 
the smallest file size, we would use the effects version; if we 
want to be able to add wiring to the movie, then a sprite 
version is preferable. 


Effects Parameters 

So far, our effect descriptions contain only a single 
kParameterWhatName atom and zero or more 
kEffectSourceName atoms. All of the built-in QuickTime video 
effects also support effects parameters, which specify 
additional information about the effect. For instance, the fire 
effect supports four parameters, which indicate the desired 
spread rate, sputter rate, water rate, and restart rate for the 
fire. The sputter rate (or decay rate) specifies how quickly 
the flames die down as they move upward. Larger values of 
the decay rate result in very low flames. (See Apple^s effects 
documentation, cited at the end of this article, for 
descriptions of the other parameters.) 

We specify a value for an effects parameter by inserting 
a parameter atom into the effect description. For instance, 
once we’ve created an effect description for the fire effect 
(by calling EffectsUtils_CreateEffectDescription), we can add a 
parameter atom to set the decay rate to 11, like this: 

my Rat a = EiidiatiS32_WtoB {11}: 

myErr = QTInsertCliild(niyEffectDesc. kParentAtonUsContainar* 
F0UR_CHAR_C0DE/decy* ). K 0, sieeof (myRate), 
imyRate. NULL): 

The type of the parameter atom indicates the kind of parameter 
we are setting, and the data in the parameter atom is die desired 
value for that parameter. 

Not all parameters are optional. With the SMPTE effects, 
the effect type indicates which of the four general classes of 
SMPTE effects (wipe, iris, radial, or matrix) the effect belongs 
to. To select a specific effect from those classes, we need to 
add a wipe ID parameter atom to the effect description. For 
instance, to specify the horizontal barn zig-zag effect (shown 
in Figure 1), we could execute this code: 

myWipe = EndianE32_NtoB(kHoria:DntalBarrLZigZagWipe) : 
myEn: “ QTInEertCbild(myEffeetDese. kParentAtomlsContainer, 
F0UR_CHAR_C0DECwplD‘} . 1. 0. sizeof (myWipe) , 

SimyWipe* NULL): 

The constant kHorizontalBarnZigZagWipe and others for the 
remaining SMPTE effects are defined in the File ImageCodec.h, 

Using the Effects Parameters Dialog Box 

When we build an effects movie, it would be nice to 
provide the user with an interactive way to set any of the 
optional effects parameters. To this end, the QuickTime 
video effects architecture includes support for displaying and 
managing the effects parameters dialog box, shown in Figure 
13^ (Sometimes this dialog box is also called the standard 
parameters dialog box,) As you can see, this dialog box 
includes a list of available effects (in this case, just the one- 
source effects) and some controls allowing the user to 
modify the parameters associated with the selected effect. It 
also includes a preview pane holding a poster image that is 
dynamically updated to reflect the current parameter settings. 
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Figure 13: The effect parameiei^ dialog box/ 

QuickTime provides the QTCreateStandardParameterOialog 
function for displaying the effects parameters dialog box, which 
is declared essentially like this: 

OSErr CITCireateStandardParanieteTDialog ( 

QTAtomContainer effectList* 

QTAtomCcintairier parameters, 

QTFaraineterDlalogOptloiis dialogOptions, 
QTParameterDlalog 'createdDialog): 

The effectList parameter specifies which effects we want to 
appear in the list on the left side of the dialog box. QuickTime 
also provides a function that can use to get a list of all effects 
that take a certain number of sources: 

myErr = QTGetEffectBList(SgEffectList, theSpecCount* 
theSpecCount. 0); 

The second and third parameters to QTGet Effects List specify the 
minimum and maximum number of sources; in this case, we set 
both of those parameters to the number of sources selected by 
the user QTGetEffectsList returns, through its First parameter, an 
atom container that holds at least two atoms fc^r every available 
effect that has the requisite number of sources. These two atoms 
specify tlie name and type of the effect. The atoms are sorted 
alphal^etically by effect name, niiat is, the atom of type 
kEffectNameAtom witli ID i is the first name alphal>etically; the 
atom of type kEffectNameAtom with ID 2 is next; and so forth.) 

The second parameter to QTCreateStandardParameterOialog 
is an atom container in which information will be returned to us 
when the user finishes selecting an effect and its parameters. We 
need to allocate that atom container ourselves, like so; 

myErr ^ QTNewAtornContainer C&gEff ectDesc) : 

aiyErr = QTCreateStandardParameterBlalogtgEffectLlst, 
gEffectDesc< 0. igEffectsDialog): 

The third parameter specifies some flags (which we set to 0 
here) and the fourth parameter is the location t>f a variable of 
type QTParameterDialog; if QTCreateStandardParameterDiaiog 
completes successfully, it returns in that location an identifier for 


the effects pammeters dialog box. We'll use that identifier in 
subsequent opemiions on the dialog box. 

Setting the Poster Images 

After w^e call QTCreateStandardPafameterDialog, the 
effects parameters dialog box is not actually displayed on the 
screen until the dialog box receives an event. (As we'll see 
shortly, we pass events to the dialog box by calling 
QTlsStandardParameterDialogEvent.) This delay gives us an 
opportunity to do any necessary ccinfiguration in the dialog 
box before the user actually sees it. The main thing we want 
to do is set the poster image or images displayed in the box. 
We set a poster image by calling the 
QTStandardParameterDialogDoAction function, which is 
declared essentially like this: 

OSErr QTStandardParaineterDlalogDcjActlon ( 

QTParametarDialog creatadDialog, long action* 
void ‘parauts): 

The action parameter specifies which action we want to perform 
on file dialog box. In QTEffeas, we wiU use these three actions: 

on uni I 


pdActionConfirmOialog 

- 1. 


pdActionSetPreviewPicture 

- 6, 


pdActionMode1essCallback 

= IZ 


To set the preview 

image, 

we use the 


pdActionSetPreviewPicture action, in which case the params 
parameter is a pointer to a pam meter dialog box preview record, 
declared like this: 

struct QTParainPrevlewReCord [ 
long fiourcelD: 

PicHandle sourcePlcture; 

i: 

The sourcePicture field contains a picture handle for the preview 
image, wliich must not be disposed until the dialog box is 
dismis^sed. The sourcelD field indicates the index of the image. A 
filter should have one preview image with this field set to 1, and 
a transition should hiive two preview images with this field set 
to 1 and 2. listing 10 shows how we would set the preview 
image for a filter 


Listing 10: Setting a preview image 


QTFifects^DisplayDbilogForSoufces 

if CroySrcTrack [*= Mill.) ( 

gPosterA = GetTrackPict(mySrcTrack* 

GetMoviePoEterTime finySrcTrackS ] ; 
if (gPosterA 1= NULL) I 

QTParamPreviewRecord myPreviewRecord; 

myPreviewRecord,sourcePicture = gPosterA; 
myPreviewRecord . aourcelB 1: 

myErr = QIStandardParameterDialogDoAction(gEffectsDialog, 
pdActionSet PreviewFicture. &myPreviewRecord): 

I 

I 
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Quicklime provides a numter of other selectors for 
customizing the effects parameters dialog box and its operation. 
For instance, to set a custom title on the dialog box, we can use 
die pdActionSetDialogTitle action selector, like this: 

StringPtr nyPtr =" QTUtils_ConvertCToPascalStrlTig(kMyTitle) : 

myErr = QTStarLdardParattieterDialogDoActlon(gEffectsDlaIog, 
pdActionSetOialogTitle, inyPtrJ : 
free(tayPtr) ; 

See Apple’s effects documentation for a complete list of the action 
selectors .supported by QTStandardParameterDialogDoActfon. 

Handling Events in the Effects Parameters Dialog Box 

Once we’ve configured the effects parameters dialog box to 
our liking, we need to start sending events to it so that it is 
displayed on the screen and the user can interact with it. We use 
the QTIsStandardParameterDialogEvent function to send events to 
that dialog box, like this: 

jnyErr = QTIsStandardParameterDialogEvent(theEvent, 
gEffectsDialog}: 

QTfsStandardParameterDialogEvent determines whedier die 
specified event is meant for the effects pammeteis dialog box (ratiier 
in the same way diat IsDialogEvent detennines whether an event is 
meant for a typical dialog boxX If the event dtx^s apply to that dialog 
Ixix, it’s liandled; in any case, QTlsStandardParameterOialogEvent 
returns a result code to its caller tliat indicates what action, if any, it 


took. We need to inspect tliat result code and reaa accordingly. 
Currently, QTIsStandardPaiBmeterDlalogEvent returns one of foLir 
result codes: 

• If codecParameterDialogConfirm is returned, the user has 
clicked tlie OK button; in this case, we need to tell QuickTime 
to fill the effect description we earlier passed to 
QTCreateStandafdParameterDialog with atoms that reflect the 
user's selections in the dialog box. Then we should close the 
dialog box and use the information in that effects descxiption, 

• If userCanceledErr is returned, the user has clicked the Cancel 
button in the dialog box. In this case, we should close the 
dialog box and perform any necessary clean-up operations. 

• If noErr is returned, the event was completely handled by the 
effects parameters dialog box code; we should proceed with 
further event processing. 

• If featureUnsupported is returned, the event was not handled 

by the effects parameters dialog box code; we should allow 
the event to be processed by our application normally. 

Listing 11 shows our definition of the 
QTEffects_HandleEffectsDialogEvents function, which we use 
to send events to the effeci parameters dialog box and 
respond appropriately. 
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listing 11: Handling dialog events 


QTEffectsJiandleEffectsDialogEvents 

Boolean QTEffects_HandleEffectsDialogEveiits 

(EventRecord ‘theEvent. Dialogltemlndex theltamHit) 

1 

/^pragma unused (theItemHit) 

Boolean isHandled = false: 

OSErr myErr = noErr: 

// pass the event to the standard efleas parameters dialog box handler 
myErr = QTIsStandardParatneterDialogEvent (theEvent* 
gEffectsDialog): 

if the result from QllsStaadaME^uameterlMogEvent tells us how to respond next 
switch (myErr) t 

case codecParameterDlalogConflnn: 
case userCanceledEm 

// the user dkked the OK or Cancel button; 
if dismiss the dialog box and respond accordingly 
gDoneWithDialog ^ true: 

If (myErr = codecParameterMalogConfirm) 

QTStandardParameterDialogDoAction(gEffectsDialog, 
pdActlonConf i rmDial og. fJULL) ; 
QTDismiasStandardParaineterDlalog (gEffectsDialog) : 
gEffectsDialog = OL: 

(lTEffects_RespondToDialogSelection(myErr): 

isHandled = true: 

break: 

case noErr: 

if the event was completely handled by QTlsStandardRtrameterDialtjgEvcnt 

isHandled = true: 

break: 

case featureUnsupported: 

if the event was not handled by QTlsStandajdParanieterDialogEvent; 
if let the event be processed normally^ 
isHandled = false: 
break: 

default: 

if the event was not handled by QTIsStandaidPaninieterDialogEvent; 
a do not let the event be processed norroally 
isHandled = true: 
break: 

1 

returnCisHandled): 

1 

Notice that the code for the (X>decParanieterDiaiogConfirm result 
code calls QTStandardParameterDlalogDoActlon with the 
pdActionConflrm Dialog action parameter; this fills in die effea 
description with the current values in the dialog tox. That code also 
calls QTDismissStandardParameterDialog to close die dialog box ^md 
the application function QTEffects_RespondToDialogSelect}on to 
respond to die user's selecdon. We won't consider the 
QTEffects_RespondToDialogSelection function in diis article, since it 
pretty much reprises code w'e've already seen to build an effects 
movie. Thai function does, however, contain some important clean¬ 
up code, shown in listing 12. 


Listing 12: Cleaning up after the dialog box is closed 


QTEffeas_RespondToDialpgScleaion 

if standard parameter box Im been dismissed; first do any necessary' clean-up 
gEffectsDlalog = OL: 

// we're finished with the effect list and movie posters 
if (gEffectList != KDLL) 


QTDisposeAtosiiContainer (gEffectLlst) : 

if (gPosterA |= NULL) 
KillPicture(gPofiterA): 

if (gPosterB 1= NULL) 

KlllPicture(gPosterB): 


Sending Events to the Effects Parameters Dialog Box 

Now we know how to send events to the effects parameter 
dialog box and how to respond to the result codes diat are returned 
to us. But when should we call QTEffects_HandleEffectsDialogEvents 
in our application code? On Macintosh systems, this is pretty easy, 
since our basic Macintosh application framew^ork calls tlie function 
QTApp_HandleEvent for every event it receives from WaitNextEvent 
Our application can inspea tlie gEffectsDialog global variable to see 
whetlier the effects parameter dhtlog box is ainently displayed; if it 
is, we'll just call QTEffects_HarxileEffectsDialogEvBnts, as shown in 
Listing 13 . 

Listing 13: Looking for events for the effects parameters 
dialog box 

QTApp^HaudlcEvcnt 

Boolean QTAppJandleEveiit (EventReoord ''theEvent) 

t 

Boolean isRandled = false: 

// see if the event is meant for the effects parameter diakig box 
if (gEffectsDialog I- OL) 

isHandled ” QTEffects_HandleEffectsEialogEventa(theEvent, 
0 ): 

return(isHandled); 

3 

On Windows, tilings are a hit trickier here. In our Windows 
application framework, QTApp_H an die Event is called only when a 
movie w^indow is open. So we can't rely on QTApp_HandleEvent 
to trigger the QTEffects_HandleEffectsDialogEvents function. 
Instead, we can use SetModeiessDialogCailbackProc to install a 
callback function to handle Window's messages that apply to the 
effects parameters dialog box. (Tliis function works equally well 
w'ith modal dialog boxes, so don't worry about the name.) Well 
call SetModeiessDialogCailbackProc like this: 

SetModeiessDialogCailbackProc (Pfont^JindowO , 
(ClTModelessCallbackUPP}QTEffscts_EffectsDialogCallback): 

The specified callback prot^edure, QTEffects_EffectsDialogCa!lback, 
is called by QTML when it's liandling events m dialog boxes. 
When our callback function is executed, QTML has already done 
any control tracking for controls in tlie dialog lx>x. If a control has 
been selected, its TD is passed to us in die theltemHit parameter. 
Listing 14 shows our definition of QTEffects_EffectsDialogCallbadt. 

Listing 14; Handling events for the effects parameters 
dialog box 

QTEffects_EffoctsDialogC3Uback 

static void QTEffects_EffectsDialogCaLlback 

(EventRecord •theEvent, DialogRef theDialog. 
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Dialogrteittlndex theltemHit) 

QTFararaDialoaEventRecord myRecord: 

tiyRecord»theEvent = theEventj 
niyRecord.whlQhBialog = theDialog: 
luyRecord^itemHit = thelteraHit: 

if (gEffectsDialog != OL) I 

QTStandairdParanteter]}iaiogDoAction[gEffectsDialog, 
pdActionModelessCallhack^ fidayRecord); 

// see if the event is meant for the efifccL't parameters dialog box 
QTEffects_HaTidleEffectsDialogEv€nts{theEvent» 
thelteiriHit) : 

1 

) 


the user has selected a set of parameters for an effect, our 
application might want to save them into a file, whence we 
can retrieve them the next time the application is run. The 
formal of these files is publicly defined and is indeed quite 
easy to read and write. 

An effects parameter file is a file that specifies an effect 
and zero or more of its parameters^ it may also specify the 
poster picture that appears in the effects f:)arameters dialog 
box. An effects parameter file is organized as a series of 
'^classic'’ atoms. Currently three kinds of atoms are included 
in one of lliese files: 


As you can see, we pass the event to 
QTEffects_HandleEffectsDialogEvents. (We also pass the index of 
the item hit, but it's ignored by that function.) We also call 
QTStancfardParameterDiaiogDoAction, this time with the aaion 
pdActionModelessCallback. This is some magic that ensures that 
QTML properly updates the dialog box and its controls. 

One last “gotcha” on Windows: we need to make sure that 
idle events are sent to the dialog box, so that it can run the effect 
in the preview pane. To accomplish this, we attach a custom 
window procedure to the dialog box by calling 
QTMLSetWindowWndProc, like this: 

QTMLS&tWlndovWndProc (FrontWindovO , 

QTEffects_CustomDialogWndProc); 

QTEffects_CustomDialogWndProc, defined in Listing 15, is called 
whenever the dialog box receives a message 

Listing 15: Handling messages for the effects parameters 
dialog box 

QTEffctts_Cuj*UJmDLilt)gWndProt: 

LRESULT CALLBACK QTEffects_CuBtoniDialogWndProc (HWND theWnd, 
UINT theHessage, UTNT wParain, LONG 1 Pa ram) 

I 

EventRecord myEvent = (0): 

if (EgDoneWithDialog (theMesBage “ 0x7FFF)} 

QTEf fectfi_Ef f ectsDialogCallbeckT^niyEveiit, 
GetNativoWindowPort(tbeWnd). 0): 

returnCDefWindowProc(theWnd< tbeNessage, wParam. IParam]); 

] 

As you can see, QTEffects^CustomDialogWndProc looks for 
messages of the type 0x7FFF (which is a special message 
produced by QTML to simulate Macintosh idle events); when 
it finds one, and if the dialog box is still active, it calls the 
function QTEffects_EffectsDialogCa[lback with an event record 
for an idle event. 


Effects PAKAMeiER Fejes 

Notice that the effects parameters dialog box in Figure 
13 contains two buttons, labeled “Save..." and “Load,..". 
These buttons allow the user to save the effects parameters 
currently displayed in the dialog box and to reload a saved 
set of parameters. For various purposes, it might be useful to 
perform these actions prograimnatically. For instance, once 


• An atom of type ‘qtfx' (required). The atom data is an 
atom container that holds information about the effect 
type and parameters. In other words, the atom data is an 
effect description. 

• An atom of type pnot' (optional). The atom data is oiganized as 
a preview resource record (of t>'pe PreviewResourceRecord). 
This atom specifies the type and index of .some other atom, 
w^hich contains tlie actual poster data. Usually the other atom is 
of type PICT. 

• An atom of type PiCT' (optional). The atom data is a picture 
tl^at’s used as the poster image in the effects parameters 
dialog box. 
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Sound Studio will allow you to make quick edits with an 
interface as easy as a text editor. Add polish to recordings 
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- AIFF, Souud Designer 2, WAVE. 

Syntem 7 Soundi and QuickTime import 

• edit with saiupte accuracy 
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Other a.toms muy be included in an effects parameter file; 
applicalions that aren't expecting other atoms should be 
smart enough to skip them. By convenlioOt an effects 
parameter file has the file extension ‘.qix'; on Macintosh 
systems, the file type is 'qtfx\ 

Currently, QuickTime does not provide any functions 
for reading or writing effects parameter files, but based on 
what we’ve learned hitherto (especially in 'The Atomic 
Cafe" in MacTech, September 2000), we can easily write our 
own. Listing 16 shows a simple routine that we can use to 
open an effects parameter file and read the data of the 'qtfx' 
atom it contains. 


Listing 16: Getting an effect description from an 
effects parameter file 


EffectsUijJs^GttEffcctDescFmmQHXFilc 

QTAtomContainer EffectsUtils_CetEffectDescFromQFXFilG 
(FSSpec *th&FSSpec) 


Handle 

myEffectDesc = NULL: 

short 

rayRefNum = 0: 

long 

mySize = OL; 

OSType 

my Type = OL; 

long 

myAtomHeader[21: 

OSErr 

myErr = noErr: 


iraaLlsI Pro 7.6 

Protesstonal List Management for 4th Dimension 

« Display and edit arrays or fields 

« Drag cells, rows or columns 

« Gives complete control of color, font, size and style 

* User resizable columns 

* Mix field display witfi catculafed columns 

* Sorting on related-one Helds 

* Full navigation key support 

* Quick setup with Advanced Properties dialog 

AreaList Pro Is a plug-in package for 4th Dimension that pro¬ 
vides editable, multi-column scrolling lists directly on your 4D 
application form. It equips you with the necessary tools to 
develop lists quickly and with increased flexibility. All features 
can be developed programmatically with AreaList Pro’s rich com¬ 
mand syntax, or through the Advanced Properties Dialog for 
easy point and click setup. 



KtriMtTEa tBLimilt (IMBir 


Automated Solutions Group 

Phone (714)375-4252 • Fax (714) 848-0382 
E-mail: sales@asgsoft.com • www.asgsoft.com 


Toll-free (800) 375-4ASG 


nyErr = FSpOpenDFItheFSSpec, fsRdPerm. fayRefNum): 
if (ayErr !“ noErr) 

g^oto ball* 

SetFPos(myRefNuift. faFromStart. 0): 

while ((myErr ^ noErr] && (luyEffectDesc = NULL)) [ 

// read the atom header at ihe currem file position 
mySize = aizeof (myAtoinHeader): 
myErr = FSRead[myRsfNum. &mySize, myAtomHeader): 
if (myErr != noErr) 
goto ball; 

mySise = EndianU32_EtoN[iiiyAtoraHeader[0]) - 

elzeof(myAtomHeader); 
myType = EndianU32._BtoN (myAtomHeader [1] 3: 

if (myType — F0UR_CHAR_C0DE(‘qtfx*3) I 
myEffectDeac = NewHandleClear(iiiySlze}: 
if (myEffectDesc = NHLL3 
goto ball: 

myErr = FSReadCmyRefNuin. ^mySize, ^myEffectDesc): 

) else I 

SetFPosCmyRefNuiii. fsFromMark* mySize): 

J 


bail: 

return ((QTAtcunContainerjmyEffectBesc}; 

1 


The effeci dL\sLTiplion returned by this function can. be 
used anywhere we use an effect description. 

Conclusion 

In this article, weVe seen how to create movies that 
contain QuickTime video effects. WeVe w^orked with 
generators, filters, and transitions, and weVe seen how to 
display and manage the effects parameters dialog box. WeVe 
also seen how to read data from an effects parameter file. The 
QuickTime video effects architecture provides a rich source of 
new capabiliries that we can tap into with some very simple 
programming. The only really new thing weVe encountered in 
this article is building effect descriptions, and even that turns 
out to be just another exercise in building atom containers. 

You already know whafs in store for us in the next 
article: were going to see how- to apply effects to images 
(not just to movie tracks). WeVe also going to see how to 
apply an effect to part of a movie, and how' to use an effect 
as the image for a sprite. At some point in the distant future, 
we'll even learn how to write our own custom effects. 
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PROGRAMMER'S 

CHALLENGE 


By Boh Boonstra, Westfordy MA 


Nassi-Schneiderman 

Perhaps you remember NassbSchneiderman diagrams as 
an alternative to traditional flow charts. Or perhaps you 
remember them as Chapin Charts. Whether you remember 
them or not, it's time to dig out those old computer science 
textbooks and bone up, because this month weVe going to 
be drawing some of them. 

There is no prototype for this Challenge, because you are 
going to build a complete Macintosh application. The basic 
requirement is that you open a text file containing valid C/C++ 
source code and generate a Nassi-Schneiderman diagram for 
each routine included in that File. To do that, you will need to 
provide menu options to open a file, allowing the user to 
navigate tlirough the file system to select a file. You should parse 
the source code and open a window' for each routine, drawing 
in the window the diagram that describes the program logic. The 
Liser must be allowed to move and resize the windows, and you 
should draw the diagram at a level of detail that fits into the 
window as sized by the user. You must provide a means for the 
user to selecl a section of the diagram, or click on a section of 
interest, and zoom in on that section. The zoomed-in display 
should increase the level of detail displayed, until no further 
increase in detail is possible. Your code must allow the user to 
switch to another application, and must properly update the 
window contents when appropriate. 

A Nassi-Schneiderman diagram consists of four simple block 
types: an instruction block, an alternative (e.g., if-then-else) 
block, a multiple choice (e.g., switch) block, and an iteration 
(e.g., do ... while) block. 

The imtmction hhck is simply a hkxk with codi^ imtde: 


y++; 


The aiterriatfm^ block looks like this: 


(?^>“xMm) &,&. (x<=xMax) 

Y \ ' X N 

<code for TRUE> 

<code for FALSE> 

WrtiVuWv 


The multiple choice block looks like this: 


4 

\ 

Switch <n) 

[\ 

[\ 

<CO^> 

<code> 

<code> 

<code> 


And the loop block- 


for (1=0; i<iMax: in-l-) 


<loop code> 


Normally, these diagrams would contain pseudo-code tliat 
describes the intent of the actual code. Obviously, we won’t have 
p.seudo-code available, so you’ll have to display something based 
on the code itself. Exactly w^hat you display is at your discretion, 
but it should provide enough information so iliat you can 
identify^ the code asscKiated with a block in the source file, 
subject to screen real estate limitations. 

In cTeaiing the diagrams, you are encouraged to provide the 
user with additional features. For example, you might allow the 
user to change the text font and text size, and tlien adjust die text 
in the diagram if more or less text fits inside the boxes. You 
might provide a Window menu with die name of each 
diagrammed routine. You might provide an option to bring up 
the full text of a block inside a window-. You can provide 
keyboard shortcuts or use mtKlifier keys to implement special 
options. You might add a magnification capability that adds scroll 
bars to the window' (in addition to the required zoom feature). 
You can add preference settings that make sense for your 
application. There miglil be a useful way to use color. 

In the event the code contains a construct diat cannot 
reasonably be diagramed (e g., a goto statement), you should 
highlight the associated blcx:k in the diagram in some way and 
treat the offending constnict as a no-op. 

This will be a native PowerPC Challenge, using the latest 
version of Code Warrior, or the development environment of 
your choice (provided I have a copy - email 
progchallenge@mactech.com to check before you use 
something else). You can develop for Mac OS 9 or Mac OS X. 
Evaluation of your entry will be subjective, based first on the 
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requirtfd feature's, then on optional features, and finally on 
general usability and look-and-feel. To ensure that I Fairly 
evaluate your solution, you should include in your 
submission a list of any optional features you incorporated. 

Three Months Ago Winner 
After a Challenge absence of more than three years, Jeff 
Mallett (Boulder Creek, CA) returns to take first place in the 
June Dots Challenge. The object of this Challenge was to win 
a round-robin lournameni of the game Dots (or Dots and 
Boxes). Dots is played on an NxN grid w^here players take 
turns connecting adjacent dots horizontally and vertically to 
enclose boxes. The player capturing the most boxes wins the 
game. The Challenge was actually scored based on 
minimizing the number of boxes captured by the opposing 
player, incorporating the usual efficiency requirement by 
adding a penalty of 1% for each millisecond of execution 
time. Solutions were also required to display the game state 
and the current score after each move, 

Jeff maintains four doubly-linked lists of boxes in gList, 
one list for boxes with 0 edges (0-boxes), another for boxes 
with I edge (1-boxes), etc. He also maintains a data stmcture 
called a 2-path (Two Path RecordType), which is a sequence of 
connected boxes each of which has two or three existing 
edges {2-boxes or 3-boxes, respectively). 

The heavy lifting is done in the ComputerTurn routine, 
and 111 try to describe the logic. If there are no 3-boxes, the 
code looks to see if all unfilled boxes are 2-hoxes. If so, any 
move is going to give a box to the opponent, so Jeff picks 
the move that gives the minimum away to the opponent. 
Otherwise, he selects a 0-box, or (as a second choice) a 1- 
box, provided It is "safe”, where an '^unsafe” box Is one for 
which adding an edge creates a 3-box. 


If there are 3-boxes, and there are safe places to move 
next, Jeff takes the 3''box and plays again. If the open edge 
of the 3-box is at the board boundary, he takes the box. 
Otherwise, he takes as many 3-boxes as he can while saving 
the moves that give the opponent a square ("handouts”). If a 
move that gives a handout captures half or more of the 
remaining boxes, Jeff makes that move. And finally, if forced, 
he makes a move that gives the opponent the smallest 
sequence of boxes. 

As the comments in Jeff's code indicate, his solution is 
actually based on 15-year-old code, translated from Pascal 
into C/C++ for the Challenge, Jeff mentions that the time 
penalty in the problem caused him to significantly “dumb 
down” the program, removing enough of the look-ahead 
code to make it a fast, if mediocre, player. 

The second-place entry, from Greg Sadetsky, is based 
(with permission) on a JavaScript program by UCLA Professor 
Thomas S. Ferguson. In addition to providing some very 
entertaining commentary that I wish we had the space to 
publish, Greg included the URL for the JavaScript code 
(http://www.stat,uda.edu/'-tom/Games/dots&boxeihtml), as well as a 
page of links to other analyses of the game 
(http://dmoz.org/Games/Paper_and_Pendl/DoTs_and_Boxes/}. 

The table below lists, for each of the solutions submitted, 
the number of cells captured by each solution in the 
tournament, the number of cells captured by the opposing 
player, the execution time in millisecond.^, and the .score 
earned by each solution (with lower scores being better). The 
table also includes the code and data size for each solution, 
and the programming language used. As u.sual, the number 
in parentheses after the entrant's name is the total number of 
Challenge points earned in all Challenges prior to this one. 


Fight Boredom 

Let’s face it: Much of programming is boring 
and repetitive. Well, that’s where the right 
tool can save days, weeks, or even months 
of your valuable time. 



Model* Viow‘Controtter 

AppMaker’s generated code uses the MVC 
paradigm. It separates the user interface 
from application logic, making code easier 
to write, '/ou deal only with abstract data; 
AppMaker takes care of the user interface. 


AppMaker 

Your Assistant Programmer 

AppMaker makes it faster and easier to make an 
application. It’s like having your own assistant 
programmer. You point and click to tell 
AppMaker the results you want, then it 
generates “human, professional quality code" 
to implement your design. 


Scriptable Applications 

AppMaker generates the 'aete' resource and 
generates code to access your data 
(Properties and Elements in the Apple Event 
Object Model) and to handle Events. 

Just $199 from www.devdepot.com B*0*W«E«R»S 

Development 

P.O. Box 929. Grantham, NH 03753 • (603) 86.3-0945 • FAX 863-3857 
bowersdcv@aol.com • http://mcmbers.aol.com/bowersdev 


Application 
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Name 

Player Opponent Time 
Ceils CeBs (msec) 

Score 

Code 

Data 

Lang 

Jeff Mallett (94) 

3218 

1362 

833.7 

2061,5 

11572 

998 

C++ 

Greg SadeLsky (14) 

3128 

1452 

1566.6 

2753.8 

17192 

1936 

C 

Ernst Munter (751) 

2529 

2010 

721.4 

3009.9 

10^ 

5f^~' 

C++ 

Tom Saxton (185) 

1914 

2666 

3262.5 

8777,5 

7220 

581 

C++ 

Randy Boring (142) 

668 

3422 531 lai 

145423.8 

17676 

498 

C 

T R. 

1752 

2297 

367,1 

2962,6 

5188 

307 

C++ 


Top Contestants 

Listed here are the Top Contestants for the Progranimer’s 
Challenge, including eveiyone who lias accumulated 20 or more 
points during the past two years. The numbers below include points 
awarded over the 24 most recent contests, including points earned 
by this month’s entrants. 


Ranh 

Name 

Points 

Wins 

Total 



(24 mo) 

(24 mo) 

Points 

1. 

Munter, Ernst 

271 

10 

758 

2. 

Rieken, Wilieke 

73 

3 

134 

3. 

Saxton, Tom 

71 

2 

18^) 

4. 

Taylor, jon^ithan 

56 

2 

56 

5. 

Wihibojg, Claes 

49 

2 

49 

6. 

Shearer, Rob 

48 

1 

62 

7. 

Maurer, Se])asLtan 

38 

1 

JOB 

It). 

Mallett. Jeff 

20 

J 

114 

11 . 

Tru-skler, IVter 

20 

1 

20 


AND iifE Top Contestants Looking fok a Recent Win 

In order to give sofne recognition to other participants in the 
Challenge, we also list the liigli scores for contestants who have 
accumulated poinLs widiout taking first place in a Ciiallenge during 
the past two years. Listed here are all of iliose contestants who 
have accumulated 6 or more points during lire ptcst two years. 


Rank 

Name 

Points 

Total 



(24 mo) 

Points 

8. 

Boring, Handy 

32 

144 

9. 

Sadeisky, Gregory 

22 

24 

12. 

Schotsman, Jan 

14 

14 

13- 

Ne(>sund| Ronald 

in 

57 

14. 

Day, Mark 

10 

30 

15. 

Jones, Dennis 

10 

22 

16. 

Downs, Andrew 

10 

12 

17. 

Desch, Noah 

10 

10 

18. 

Duga, Brady 

10 

10 

19. 

Fazeka-s, Miklos 

10 

10 

20. 

Flowers, Sue 

10 

10 

21. 

StJX3Ut, Jfx: 

10 

10 

22. 

Nicolle, Ludovic 

7 

55 

23. 

Hala, Ladislav 

7 

7 

24. 

Leshner, Will 

7 

7 

25. 

Miller, Mike 

7 

7 

26. 

Widyatama, Yudlii 

7 

7 

27. 

Heithcock, JG 

6 

43 


There are three ways to earn points: (1) scoring in die top 
5 of any Challenge, (2) being the first person to find a bug in a 
published winning solution or, (3) being the first person to 
suggest a Challenge that I use. The points you can win are: 


1st place 

20 points 

2nd place 

10 points 

3rd place 

7 points 

4 th place 

4 points 

5th place 

2 pomLs 

finding bug 

2 points 

suggesting Challenge 

2 points 


Here is Jeffs winning Boxes solution: 

Boxesxpp 

Copyright © 1986 2001 
JeffMaliett 

// Dots & Boxes 

// 

// Copyright 193(>20a I Jetf Mallett. AB rights rcsemd. 

// For Bceasing ccmtaci jcfrm@;dUio[m)rg»ines.com 

// 

//Written in Lightspeed Riscal for the Mac 
// \m\ revi'iion in Paneal: Oct N, 1986 

// Ported from PiLseal lo cye++ and adapted for contest: May-jimc 2001 
// (Tt uses inline/new/delete/templaie/etc., but iCs really more C 
// than C++ since there are no classes. If 1 had more time 1 would 
// have ecmvertetl ii to Ix! objeet-Oriented as well,) 

// 

// Programmer's Cbjillenge Entty^ 

//This‘S version docs not play Dots Sl Boxes eompkiely naively — e.g. 
// it understands the sacrifieing boxes icj keep the initiative — but 
// neither does it play very skillfuBy. lliLs is Ixeaase the 
// challenge awards points based on boxes and lime taken, not 
// (jn whtj aetiially wins the games. As penalties are awarded 
// for every millisecond of thinking, a quick mediocre player is 
// likely to gain more points than a slow master Therefore 1 
// dumbed down the program considerably by ripping out code that 
// determined liow to eorreeily play networks of l-lioxes 
// connected with 2 paths of lengdi 1 or 2. Now the program 
// doesn't have a elue what to do with nnsiife Lboxes and never 
// sacrifices Ixrxes early in the game, but it also saves a 
// lot of processing time. 

// 

/Meflno DRAWING 
^define EDGECOUNT^FIELD 
//#define (:tK)RDINATE^F]ElDS 

//define TICKSEED LMGetTicksO 
//defino ASSERT assert 

//include <assert.h> 

//include <stdllbKh> 

//include <limits,h> 

//include "Dots.h" 

/j/incIudG <LovMeni,h> 


ENUMS 

snum direction [lsft=0, up, right, down!: 
enum who lflrstplayGr=0, secondplayer]; 
enum pathdirection ibehind^O, ahead!: 

// BOROER^VALUE: box is off the board 

// MAILK_VALUE: when calcuJating a path, a txix with this value is already^ c>n it 
enura boxflag fB0RDER_VALUE--2, MRK_VALUE=’1, N0_VALUE=Di: 

// NCyr_LOOP; 2-path lias two end.s 

//ALMOST_LOOP: 2-patli's ends terminate at the same 0-box or I-box 
// LOOP: 2-path has no ends 
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^suesl-^: 


THE EASYr COmWAMl 




- The MacTech CD-ROM with 




w^w.mactech. com 




THINK Reference is the 
ssendal reference resource for 
intosh programmers. This 
D includes the THINK 
[ference personal database 
^system and a wealth of 
Macintosh programming databases, 
featuring almost 200 issues of the 
journal of Macintosh 
programming - MacTech Magazine. 

This release also features the 
THINK Reference Compiler, which 
allows you to compile HTML files 
into your own compact, searchable 
THINK Reference databases. 


PO Box 5200 • Westlake Village, CA • 91359-5200 
800/MACDEV-l (800/622-3381) • Outside US/Canada: 805/494-9797 
Fax: 805/494-9798 • E-mail; orders@devdepot.com 

















enutn loopvaliie tNOT_LOOP=0, ALMOST_LOOP* LOOP]: 


TYPEDEFs 

typedef struct EoxRecordType'* PtrToBoxRecotd r 
typedef struct TwoPatMecordType* PtrToTwoPathRec&rd: 

struct TVoPathSecordType I 
Int pathsize: 
loopvalue loop; 

PtrToBoxRecord path; 

PtrToTwoPathRecord previous< next; 

1 ; 

struct BoxRecordType [ 

tfifdef COORDINATE_FIELDS 

sho rt xcQord, ycoord; // Uxation of box 

#endif 

#ifdef EDGECOUNT^FIELD 

short ed Recount; // Number of edges 

//^endif 

Boolean edges [4]: //Is tliere an edge in this direction? 

PtrToBoxRecord previous» next; 

// previous & next elements in 

gLlstf] 

boxf la g flag: // Used for marking borders and searched boxes 

// 2-paih info 

PtrToTwoPathRecord tvopath; // tJie 2'paLh this is in 

PtrToBoxRecord pnext [2] ; // the two conneaing boxes in the 2-path 

h 


#defitie EKD_P 0 R_LIST 2 (pList. whichList, start) \ 
pLiSt = pLis t->next; \ 
if (IpList) pList gList[whichList] ^ \ 

1 while (pList Start); \ 

J 

^define FOR_EACH_OPEN_DIRECTlON(box) \ 

[ direction f_dir = left: const Boolean ‘pEdges = (box)- 
>edges: \ 
do [ \ 

if ( l*(pEdges + (fjir)) ) f \ 

PtrToBoxRecord f3ox = Go (box, f_dir): 

^define EliD_FOR_EACH_OPEN_Dl RECTI ON \ 

1 \ 

1 while ((f_dir = (direction)(f_dir+l)) down): \ 

I 

^define FOR_FATHDIRECTION(pdir) pdir = behind: do 
#define END_FOR_PATHDIRECTION(pdir) while ((pdir “ 
(pathdlrectlon)(pdir+l)) <= ahead); 


PROTonrypES 

#ifdef DRAWING 

extern void DrawInitial(int x^ int y, who person): 
extern void DrawScore(vho w]; 

extern void DrawMovednt x, int y, enum direction d) : 
extern void InitialDrawlngO: 

#endif 


struct MoveRecordType I 
PtrToBoxRecord box; 
direction dir; 

I: 


GLOBALS 

PtrToBoxRecord gBoxes : // Array holding all the boxes 

int gAr ray Si zeY: // Array width of gboxes 

int gBoardSizeX. gBoardSizeY:// Sia' of the IxianJ in Nixes across and 

down 

PtrToBoxRecord gList [4J: // Pointers itj doublylinked lists of n-edge boxes 
Pt rToBoxRecord gLlstBooktna rk [ 21 ; 

// Next box on gList[nI lo knik at ftir a safe mtivc 
int gOff set [ 4 ] : // Offset in glioxes for gi)mg this direction 

Pt rToTwoPathRecord gTwoPaths [3] :// Pointers to a dijiibly-linked lists of 2- 
paths 

//I0|:lengiJi>2 [Ihlengtli I 12]length 2 
Boolean gPathsComputed: // Have the 2-paths ever been recorded in 

gTwoPaths? 


Boolean gSafe[2]: 

// Is there a move on an n-box that dtjesnt give die opponent a 3-box? 
Boolean gSafetyCheckWeeded; 

// Need to check whether position has liecome dangerous? 
PtrToBoxRecord gLastSafeBox [2] ://Thc most recent Nix found safe on list n 


int gScore[2]: 

eonipleted 

Int gTotalScore: 

int gMaxScore: 

who gCurrentPlayer; 


// gSoirelw I is the * of boxes player w has 

// TJie sum of the two player's score 
//The maximum possible value of gTotalScore 
//The current player 


void InitializeC): 

void CheckSafety(int listindex); 

void Clear {PtrToB.oxRecord box) : 

void ComputeAPathCPtrToBoxRecord poslnedgellst* 

PtrToTwoPathRecord existingtwopath): 

void ComputePaths(); 

void UpdatePathFromiPtrToBoxRecord hox); 

void AddEdge(PtrToBoxRecord box, direction d. who whoseturn): 
int ExpectedScore(FtrTaTwoPathRecord ignoreThis): 
int CountTinyTwoPathu( }; 

int CountSurroundlngPathSizes(PtrToBoxRecord box): 
PtrToTwoPathRecord MinimuniTwoPath{); 
void HandOut(int hotype, HoveRacordType ^move): 
direction HardHearteMandout(PtrToBoxRecord hox) : 

Boolean FindSafeMoveOnList(int listindex, MoveRecordType 
fimove); 

void ComputerTurn[MoveRecordType &move); 

Boolean MakeRealMove(MoveRecordType move, who whoseturn); 
void ConvertFromDotLine(MoveRecordType Groove, const DotLine 
&dotline): 

void ConvertToDotLlne[MoveRecordType move. DotLine idotline); 


INLtNES 

// Returns X coordinate value for the box 
inline int GetX [PtrToBoxRecord box) 1 
#ifdef COORI1INATE_FIELDS 
return box->xcciord: 

(felse 

return (box - gBoxes] / gArraySlzeY; 
ilfendlf 

I 


MACROS 

/define EVEN(x) ({(x) & 1) ^0) 

^define DDD{x) (((x) S 1) !“ 0) 


^define EDGE(x,y,d) gBoxes tx’‘gArraySi 2 e¥ + y],edges[d] 

#define B0X(x,y) (&gBoxes [x*gArraySizeY -i- y]) 


#dcfine F0R_LIST{pList, whichList) for (pList = 
gList[whichList]: pLlst; pList = pLiEt->next) 


{/define F0R3TST2 (pLlst. whichList, start) \ 
if (gList[whichList]) [ \ 

if ([start II NumberOfEdges(start) 1= whichList) \ 
start ' gList [whichList]: \ 
pList = start: do { 


// Returns Y coordinate value for the box 
Inline int GetY (PtrToBoxRecord box) ( 

#ifdef COORDINATE_FIELDS 
return box’')ycoord: 

{/else 

int dindex = box - gBoxes: 
int xcoord = dindex / gArraySizeY: 
return dindex - xcoord * gArrayBizeY; 
i/endif 

I 

// Returns the box in direction dir 

inline PtrToBoxRecord Go (PtrToBoxRecord box, direction dir) 

[ 

return box + gOffset[dir] ; 
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if Rerums the opposite path direction to the given parh direction 

inline pathdirection OppositePathDirection (pathdlrection 

pathdir) { 

return Cpathdirectlon) [1 - pathdir): 


// Returns the direction opposite to the given direction 
inline direction OpposlteDirection (direction dir) f 
return (direction) ((dir+2)X4): 

[ 

// Returns the next direction in a clockwise fashion 

inline direction NextBirection (direction dir) ( 

return (dir ^ down) ? left : (direction) (dir + 1): 

I 

// Goes to the next player 

inline void HextPlayer {who &whoseturn) [ 
whoseturn “ (who) (1 - wboseturn)^ 

) 

// PrtKluces a tandum mimbcr between 0 and n-1 inclusive 
inline int rnd (int n) [ 

return ((long) rand() n) / ({long)RAWD_MAX + 1): 

} 

// Returns a direction chosen at random (or at least different) 
inline direction RandomDirection () [ 
return (direction) (rand() ii 3) ; 

1 

// Given a 5i>ox on i 2‘path, returns the path direction out of the 
inline pathdlrection OutPathCirection (PtrToBoxReccird box) [ 
return box->pnext[ahead] ? ahead : behind; 


// Returns true iff the box is within the boundaries, 
inline Boolean Isinsideloard (PtrToBoxRecord box) { 
return box’>flag != BORDER_VALUE; 

I 

// Returns a direction randomly such that ’box ^edgesid] 
inline direction GetOpenDlrection (PtrToBoxRecord box) 1 
// cycle through directions starting at random direction dir 
direction d = RandomDlrectionO : 
const Boolean ‘p = box-)edges: 
while {'“(p-i-d)) * 

d “ NextDirectlon(d); 
return d: 

1 

// Sets up a move from box in a random direction with no edge 

Inline void PlayAny [PtrToBoxRecord box. MoveRecordType 

Sttnove) I 

movePbox = box; 

move.dir - GetOpenDlrection(box): 

} 

// Plays a move on the path p 

inline void PlayMoveOnFath(PtrTQTwoFathRecord p, 
WoveRecordType Wove) ( 
move.box - p~)patb: 
move.dir = (p->pathsiae =2) 7 

HardHeartedHandout(move.box) ; 

GetOpenDirectlori(move.box): 

I 

// Returns whether or not boxes a and b are connected 

inline Boolean AreConnected[PtrToBoxRecord a. PtrToBoxRecord 

b) ( 

F 0R_EACH_0PEN_D IRECT T ON (a) 

[ 

if (f„boK = b) 
return true; 

I END_FOR_EACH_OPEN_DIRECTION; 
return false: 
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engineering inc. 
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technology and 
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Sixteen years of experience coupled with the resources 
and flexibility you need. It's no surprise that our 
achievements are integrated into many of the products you 
and your customers have come to rely on every day. 
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Prosoft Engineering, Inc., is your source 
for cost-effective, on-time, custom 
cross-platform software solutions 
and services. By uniquely integrating 
Software Engineering, Quality 
Assurance, and Project Management, we 
offer you the solution you need. 
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We have the best engineers around. 
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• Big libraries: We ported the Oracle 8 client libraries which .Apple ships today in CK X Server. 

• Serious drivers: We ported 3dfx's Clide and wrote Voodoo2 and Rendition drivers for OS X Server. 

We've written new mouse drivers for OS X Server and joystick drivers for OpenStep. 

• New apps: We wrote OmniWeb, the only native OS X web browser, and OmniPDF, the native Acrobat 

viewer for OS X. 

Mac OS X is what we do. Let us help you do it, too. 
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// Returns the number of edges of die box 
inline int NumberOfEdges (PtrToBoxRecord box) { 
#ifdef EDGECOUNT_FIELD 
return box->edgeco\mt: 

^^else 

int count = 0: 

Boolean *p = box->edges: 
if (*(p'H-)) -H-count: 
if (''(p-H-)) -H-count; 
if (‘(p-H-)) -H-count; 
if (*p) ++count; 
return count; 

#endif 


LISTTEMPUTES 

//Adds the element to the begin iring of the given list 

template(class T) void AddToListCT element. T &list} { 
element-)previous = NULL: 
element->next = list; 
list = element; 
if (elementOnext) 

element->next->previous ^ element; 

S 

// Removes the element from the given list 

teTOplate<class T) void RemoveFromList(T element, T ^list) \ 
if (elementOprevioua) 

element->previous->next = element->next: 
else 

list = element -)next; 
if (element->next) 

element-)next->previous = element->previous; 


// Inserts toinsert into the list after the onlist b()x 
// Note; toinsert must not lie on a list currentiy 

teinplate<class T> void InsertAfter(T toinsert. T onlist} < 
if (onlist->next) 

onlist'>next*>previous ™ toinsert; 
toinsert')next - enlist')^next; 
onlist->next ^ toinsert; 
toinsert->previous - onJist; 


// Adds path to the front of the appropriate gTwoMhs list 
inline void AddToPathsList(PtrToTwoPathRecord path) I 
AddToList(path. gTwoPaths[path->patbsiae <= 2 ? path- 
>pathsize ; 0]); 

) 

// Removes path from the appropriate gTwoPaths list 

inline void RemoveFromPathsList(PtrToTwoPathRecord path) \ 
RemoveFromLlst(path. gTwoPathstpath->pathsize <= 2 7 path- 
>pathsize ; 0]}: 

J 


InlUali^Ee 

// Sets np variables for a game, 
void Initialize 0 
{ 

int i, j: 

int arraySizeX, arrayElements; 
srand(TICKSEED): 

arraySizeX = gBoardSizeX -1 2; //tajuderson each side 
gArraySizeY - gBoardSizeY -1^ 2; 
arrayElements = arraySizel * gArraySizeY; 
gBoxes - new BoxRecordType [arrayElements]; 

ASSERT(gBoxes); 

gOffset[left] = -gArraySizeY; 
gOffset[up] - - 1 ; 
gOffset[right] = gArraySizeY; 
gOffset[down] = 1; 

PtrToloxRecord p = gBoxea; 
for (i = 0; i ( arraySizeX; i"H-) 
for (j = 0; j < gArraySizeY; j-H-) 


[ 

p->edges[left] = p-)edges[up] = p'hedges[right] = 
p-)edges [down] = false: 
p->flag = BORDER^VALUE; 

p->pnext[ahead] ^ p->pnext[behind] = NULL; 
p-)t¥opath “ HULL: 

#ifdef C00RDINATE_FIELDS ■ 

p->xcoord = i; p->ycoord = j: 

Jfendif 

lifdef EDGECOUNT_FIELD 
p->edgecount = 0; 

#endif 

++p; 

1 

gLiSt[0] - BOX(l.l); 
gList[0]-)prBvious ~ NULL: 

for (i = 1: i <” 3; 1 ++) 
gList[i] = MULL; 

PtrToEoxRecord last = HULL; 

for (i = 1; i (= gBoardSizeX: i-H-) 

[ 

p = B0X{i. 1): 

fQr(j “1; j (= gEoardSizeY; J-H) 

1 

p->flag - N0_VALUE; 
if (last) 

I 

last->next == p; 
p-)praviouB = last; 

1 

last = p: 

-^p; 

] 

1 

last-)next = NULL; 

// Mix up list elements randomly 

for (i = gBoardSizeX; i >” I; i -) 
for (j “ 1: j (“^ gBoardSizeY; j 44) 

1 

int 12 - rnd(gBoardSizeX)41; 
int j2 “ rnd(gBoardSizeY)+1: 
if (i!-i2 II Jl=j2) 

RemoveFromList{B0X(1. j). gLlst[0]): 
InEertAfter(B0X(i. j), B0X{i2. j2)); 

I 

I 

ASSERTf[gList[0]->pravious): 

gSafe [0] “ gSafe[l] “ true; 
gPathsComputed = gSafetyCheckNeeded = false: 
gMaxScore = gBoardSizeX * gBoardSizeY; 

gTotalScore = gScore[firstplayer] ^ gSeore[secondplayer] = 

0 ; 

gListBookmark [0] = gLlstBookmark [1] = 

gLastSafeBox[0] = gLastSafeBox [1] = NULL; 

I // Initialize 


ENGINE 


ClheckSufety 

// Re-e’V'aiimies gSafe 

// [f we canY add an edge to a 0-box or 1-box witliout changing 
// a 2-box into a 5l>ox set gSafe[listindex]=false 
void CheckSafety(int listindex) i 

// Optimizatioii: Check the box that was found safe last time 
if (gLastSafeBox(listindex]) 

L 

if (NumberOfEdges(gLastSafeBox[listindex]) <= 1) 

[ 

FOR_EACH_OPEN_DIRECTrON(gLa3tSafeBox[listindex]) 

I 

if (NutnberOfEdges(f, box) 1= 2) 
return; // safe 

) END_F0R_EACH_0PEN_DIRECTI0N: 

) 

gLastSafeBox[listindex] = NULL; 

J 
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// Check 0 and 1 lists 
FtrToBoxRecord box: 

F[}R_LIST(box, listing ex) 

[ // Check a box on list 

FOR_EACH^OPENJIRECTIOM(bDx} 

{ 

if (NumberOfEdges(f_hox) 1= 2) 

I 

gLastSafeBox[listindex] = box; 
return: 

} 

I END_F0K EACH„OPEH,DIRECTION; 

I 

gSafe [listindex] = false: //unsafe 
j // CheckSafctj' 


Clear 

// initialiwji^dnitialixes the path data for a single record 

void Clear (PtrToBoxRecord box) [ 

PtrToTwoPathRecord p = box-)twopath: 
if (p) 
f 

RemoveRromPathsLlst {p] ; 
if (!-p->pathsiKe) 

\ // Box is only thing on twopatJi 

delete p: 

1 else 
1 

AddToPathsList(p): 
if (p->patb — box) 
i 

ASSERT(box’>pnext[ahead]); 
p->path = box->pnext[ahead]: 

I 

pathdireotion pdir = OutPathDirection(box); 
box->pnext[pdirj->pnext[OppositePathDirection(pdir)] " 

NULL: 

I 

box-)tWDpath “ NULL; 

box->pnext[ahead! - box->pnext(behind] = NULL: 

) 

] // Clear 


OjmputeAPath 

// Given a 24iox or a 34)ox, computes the path from that box 
void ComputeAPath (PtrToBoxReoord posinedgelist 
FtrToTwoPathRecord existingtwopath) I 

Boolean pathend; 

PtrToBoxRecord temp: 
pathdirection pdir: 

int pathlength = ’ 1: //set to 4 l>ccaase posinedge is counted twice 

PtrToBoxRecord end[2j* beyondend [2] ; 
beyondend[ahead] = beyondend[behind] - NULL; 
loopvalue loop = NOT_LOOP: 

FtrToTwoPathRecord twopath: 

if (exiEtlngtwopath) 

f 

twopath - existingtwopath: 

RemoveFromPathsList(twopath): 

1 else 

t 

twopath = new TwoPathRecordType': 

ASSERT(twopath): 

[ 

F0R_PATHI] IRECTION (pdir) 

\ // each iteration moves to the end of the path in the beliind/ahead 

direetjon 

temp = posinedgelist: 

do { // each iteration marks one more square in the path 

pathlength-i-i-; 
temp->flag = MARK_VALUE: 
t emp-)twop at h = two p ath: 
pathend = true: 

// dieck for a continuation of the path in the pdir direction 
F0R_EAGH_0PEN_D1RECTI0N(temp) 

[ // each iteration checks one direction for an adjoining 2/3-5quare 


// don’t need to check if f_box inside lK>arid because borders have 
// BORDER_VALUE 
if (!f_box->flag] 

[ // found square next to current square that hasn't been marked 

int n = NumberOfEdges(f_box); 
if (n >= 2) 

! 

// ineJude this square in path 

temp-)pnext[pdir] = f_box: 

f_box->pnext[OppositePathDirection(pdir) ] = 

temp; 

temp “ f_b£>x: 
if {n = 2) 

pathend = false: 
else // n = 5 

I // f_box is on path so add it, but don't look further 
pathlength++: 
temp->flag = MARK_VALUE: 
tefflp->twopath = twopath; 

\ 

break; 

] 

//n<2 

if ( pdir — ahead || temp I” posinedgelist } 

beyondend[pdir] = f_box; 
break; 

1 

[ 

f END_F0R_EACH_0PEN_I3IRECTION; 

// Either all directions have been looked at or a path conUnuation has 
// been found 
i while (Ipathend] s 
temp->pnext [pdir] = NULL: 
end [pdir] = temp: 

] END_FOR„.PATHDIRECTION (pdir); 

// Clear flags 

for (temp = endlahead] : temp: temp = temp->pnext[behind] ) 
tOTnp->flag - N0_VALUE: 

// Is a loop or near loop? 
if [pathlength > 2) 
i 

if (beyondend[ahead] beyondend[ahead] ™ 
beyondend[behind]) 

loop - ALMOST^LOOP: 

else if (AreConnected(end[ahead]* end [bebind]]) 
loop = LOOP: 

1 

twopath->pathsize - pathlength: 
twopath->loop - loop; 
twopathOpath ” end[bebind]: 

AddToPathsList(twopath); 

] // ComputeAPalh 


ComputePiiths 

// Finds all 2-paths and stores them by fi>nuing a doubly-linked list for each 
path 

void ComputePaths() [ 

PtrToBoxRecord posinedgelist; 

FOR„LIST(posinedgelist* 2) 

I 

if ([posinedgelist'>twopath) 

ComputeAPath[posinedgelist, NULL): 

// Compute path containing this element 
I 

gPathsComputed = true: 

1 // CaimputePatlis 


UpdatePathProm 

// Updates the paths that the newly changed box was in if needed 
void UpdatePathFrom (PtrToBoxRecord box) I 

int count: 

// Update path lists 
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count = NumberOfEdges(box); 
if (count = 4) 

Clear(box); 
else if (count = 2) 

( 

if Cuuid be added to a 2-path 
PtrToTwoPathRecotd twopatb = I^LJLL; 

P0R^EAGH_0PEN_DIRECTION(box) 

[ 

if (f_b ox'> twop atb) 
if (Itwopath) 

twopath = f_boK->twopath; //Recalculate this 2'path 
else if (f_box->twopath != twopath) 

[ // Combining two 2‘patlis 

RemoveFromPathsList(f_box-)twopath); 
break; 

1 

] END_F0R_EACH_0PEN_DIRECT10N; 

Con3put8APath(boXt twopath) : 

I 

else if [count = 3 && 

] [box->twopath box->tvopath->pathsi 2 e = 1)) 

// don't ne^ to update a length 1 path 
GomputeAPath(box^ box -)twopath); 

) // UpdatePathFrom 


AddEdge 

// Adds an edge to box at x,y and direction d. If die edge completes a square 
// update score, etc. 

// If safe might need to dianged then checkneeded will be set to uue, 

void AddEdge (PtrToBoxRecord box. direction d^ who whoseturn) 

t 

box->edges[d] = true; 

#ifdef EDGECOUNT_FIELD 
++box->edgecount; 
tfendif 

if (1 IsInaideBoard (bO’x)) 
return: 

int count = NumberOfEdges(box); 
if (count = 4) 
f 

gScore[whoseturn]++: 

#ifdef DRAWING 

DrawScore(whoseturn); 

DrawInitial(GetX[tiox) . GetY{box) , whoseturn) ; 
i^fetidif 

++gTotalScore; 

RemoveProinList (box. gList [3]) : //Take box off of old edge list 
// Don't bother putting it on gList|4] 

I 

else 

f 

RembveProtnList [box. gList [count - Ij}: //Take box off of old edge 
iisl 

AddToLis t (box. gList [count]) ; // Add box to the beginning of a new 
list 

If (count = 2) 

gSafatyCheckNeeded = true: 

J 

I //AddEdge 


ExpectedScore 

// Return estimate of tlie number of boxes well captiue 

int ExpectedScore(PtrToTwoFathRecord ignoreThis) I 

ASSERT(gPathsCoTnputed) : 

int expected, tinycountl, tinycountS. loopcount[3]; 

loopcount[N0T_LD0P] = loopcount[ALMOST_LOOP] = 

loopcount[LOOP] = tinycountl = tinycount2 = 
expected - 0: 

// Count 


FtrT 0 TwoPathRecord p: 

for (p = gTwoPaths [1] ; p; p = p->next) 

++tiuycount1; 

for (p = glVoPaths[2] ; p; p = p')next) 

-H-tlnycount2; 

for (p = gTwoFaths|0] : p; p = p-)next) 

[ 

expected p->pathsi 2 :e; //Add boxes for 2-paths 
-H-loopcount [p-)loop] : 

) 

// Subtract out ignoreThis 
if (ignoreThis->pathsi 2 e = 1) 

-tinycountl; 

else if (ignoreThis->pathsise ~ 2) 

-tinycount2; 
else [ 

expected -- IgnoreThis’>pathsiae; 

-loopcount[ignoreThis-)loop]; 

] 

if (loopcount[N0T_L00P] || loopcount[ALM0ST_L00P] || 

loopcount[LOOP]) 

i 

// Subtract handotits 

expected -= loopcount[NOT_LOOP] * 2; 
expected loopcount [ALJ^OST_LOOP] * 3; 
expected ’= loopcount[LOOP] * 4; 

// but disregard final handout 

expected +•= loopcount [NOT_LOOP] 7 2 ; 4: 

I 

// Add Ixixes for tiny 2-paihs 

expected += tinycountl /2 + 2 * (tinycDunt2/2) ; 

// Get half of each rounded down 
if (ODD(tinycountl) A& ODD[tinycount2}) 
expected += 2 : // Get last [2L e g. 1 111 and I [21 

return expected; 

// BxpcctedScore 


CountTinyTwoPaths 

// Counts [engih=l 2-paths and lcngth=2 2-paths (no 3^s). 
int CountTinyTwoPaths ( ) [ 

int count - 0; 

PtrToTwoPathRecord p: 
for (p = gTwoPaths[1]: p; p - p-)next) 
if (NumberOfEdgesfp->path) ““ 2) 

-H-count; 

for (p - gTwoPaths[2] ; p: p = p->next) 
if [NumberOfEdges(p■)path} ™ 2 hh 

NuiiiberOfEdges [p->path->pnext [ahead] ] = 2] 

-H-count; 

return count; 

I // GountTinyTwoPaths 


CountSurraundingPathSizes 

// Rettirns the number of boxes on all the surrounding 

// 2-paths, (Some may be counted more than once.) 

int CountSurroundingPathSises(PtrToBoxRecord box) ( 

int count - 0; 

FO R_EACH_0 PEN_DIRE C TIDN(b ox) 

I 

if (f_box->twopath) 

count += f_box->twopatb->pathEize; 

] END_F0R_EACH_0PEN_DIRECT10N: 
return count: 

} // GountSurroundingFathSi^ies 


MiiiimuniTWoPath 

// Returns the smallest 2-patb. 

FtrToTwoPathRecord MinimuniTwoPath () [ 

ASSERT(igList[3]); 
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if (E gPathsComputed) 

ComputePathsO : 

int minvalue = INT^MAX: 

PtrToTwoPathRecord min, p; 

if {gTwoPatlisIl]) 
return gTwoPaths [1] ; 

if (gTwoPaths [2]3 

return gTwoPaths [2] ; 

for Cp = gTwoPaths[0] ’ p: p = p->next) 

[ 

Int size = p->pathsize: 
if [p->loop 1= LOOP) 
i 

size += 3: //Ptnalixe Z only a 2-liandom Irmead of a 4- 

handout 

// Also give 1 penalt)^ since we’d mudi rather be left with non-loop 
// than a kjop at the very end, because we won’t get the last handout. 

if (p->loop -- ALMOST_LOOP hk size < mlnvalue) 

( 

PtrToBoxKecord box = p‘>path: 

FOR__EACH_OPEN_DIRECTrON(box) 

[ 

if (NumberOfEdgesCf_box) 1) 

[ 

// f_box is connected to both edges of this Z-path 
// plus one other 2-path. Filling in this 2-path 
// will cause the two 2-paths to be omncctcd, stJ 
// the size should be calculated as die total of 
// both paths + I for the I-box + 3 for the penalty 
// (size is subtraaed because the almost loop is 
// counted twice) 

size = 4 + CourttSurrouTidlngPathSizes(f_bo>!:) ■ 

size; 

break; 

1 

J ENDJ0R_EACH_0PEHJIRECTI0M: 

I 

I 

if (size < minvaluej 

{ 

minvaiue = size: 
min = p; 
if [size — 3) 
break: 

I 

I 

return min: 

I // MinimumTwoPath 


HandOiit 

// {uven a HandOut type (cither 2 or 4) and that every box on the 3's list is 
// either a 2 or hand out. HandOut finds a hand out of the indicated type in 
// the 3’s list and sets move to do this hand out. 
void HandOut (int ho.type* MoveRecordType &move) t 

PtrToBoxRecord temp; 

pathdirection pdir: 

FGR_LIST(teiEp, 3) 

I 

if (tenjp-)twQpath->pathElze = ho_type) 
f // HandOut 

pdir = OutPathDirectlon(temp): 
move,box = temp->pnext[pdir]; 

F0R_EAGH_0PEN_DIRECTI0N [move. box) 

I 

if (tlslnside£oard(f_box) |[ temp 1= f_box) 

move,dir = f_dir: 

return: 

) 

] EKB_FOR„EACH_OPEN_DIRECT10K: 

break: 

1 //if 

1 


I // HandOut 


HardHeartedHandoui 

// Given a 2 ^k on a 2-p3th of length two, returns the 
// correct direction that a new edge should be placed, 
direction HardHeartedHandout (PtrToBoxRecord box) I 

F0R_EACH_0PEOIRECTI0N (box) 

f 

if (NumbetOfEdgea[f_box} = 3) 
return f_dir: 

} ENB^F0R_EACH_0PEN_DrRECTI0N; 

ASSERT Co); // should never get here 
return left: 

] // OardHeanedHandout 


FindMeMoveOnUst 

//Tries to find a safe move on gli5t[listindexl 

// If so, set move and return true 

// If not, these boxes are now unsafe. Return false 

Boolean FindSafeMoveOnList (int llstlndex, MoveRecordType 
^rnove) E 

PtrToBoxRecord box: 

// If any lepi adjacent element is !~2 or outside board, take it 
E0R_LIST2 (box, listlndex, gLlstBookmark [lletindex]) 

t 

direction k, d; 
d = k = RandomDirectlonC): 
do I 

if Ctbox->edges[d]3 
I 

PtrToBoxRecord box2 = Go(box. d): 

if (EIsInsideBoard(box2) || NumberOfEdges (box2) 

2] 

I 

gListBookmark[listindex] = box->next; 
move,box ^ box; 
move-dir “ d; 
return true; 

1 

} 

d ^ NextDirectlonfd): 
j while (d != k); 

I END_F0R_LIST2Cbox, listindex, gListBookmarkflistindex]} 

gSefe[listindex] = false: 
return false: 

] // FmdSaftrMovcOnLisl 


QjmputcrlAuTi 

// Come up with a move for the ecimputer 

void CompUterTuxii(MoveRecordType ^move) 1 

PtrToBoxRecord temp; 

// generate computer's move 
if {!gList[3]) 

( 

if ([gList[0] kk IgLifitflJ) 
f // must pick a 2-bt>x from a 2-path 
PlHyMQveOnPathCMiniroum'rwoPathO , niove); 
return: 

I 

// (g^tm f=NULL or gListI 1]!=NUI1) and !gList|31 
//Try safe boxes on lists 

if {gSafe[D] kk FindSafeMoveOnList(0, move)] 
i 

return; 

1 

if (gSafetlJ && PlndSafeMoveOnLlst(i, move)) 

f 

return; 

} 

// AH bad dioiees: all O’s and 1 ’s are adjacent to 2"s 
if (! gFathsCotEputed) 

ComputePathsO : 
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// now count how many 2’s in a row— if onci take it 
// — if two, take it (put f between 2"s) 

PlayMoveOnPa th[MinimuraTvoPath(). move); 
r&turn; 


// gUstl3]!=NUlI 
if (gSafetyCkeckUeeded) 

f 

if (gSafe[0]) 

CheckSafety(O )\ 
if (gSafedl) 

CheckEafetyCl); 
gSafetyCheckNeaded = false; 


if (gSafelO] \ \ gSafe[l] | |: ]gList[2] M 

gMaxScore gTotalScore <= 4} 

t 

// Note; If the number of tmtaken boxes is <= 4, then always 
// take a box, since hand-outs can’t be better 
PlayAny(gList[3], move); 
return: 


if (r gPatheComputed) 

ComputePaths() : 

// unsafe && gList|21l=NULL && gList|3|E=NULL 
// while not at end of 3's list do 

// if the box connected to the 3-box is not a 2-box (or is outside the board) 
// then take it 
FOR^LIST(temp* 3) 
f 

if (1 tettip->tTvopath) 

{ 

PlayAny[temp, move): 
return: 


// Behjfe we liand out Lhouglt, let’s see if there arc any 
// tiny 2 paths where 2 or 4 handouts don’t exist. 

// These change the initiative, 
if (IgList[l]) 

E // special unsafe 1-box configurations arc not etjunted 
int tiny2patlis = CountTinyTwoPaths () r 
if { 0 DD[tin 72 paths)) 

[ //Wt do not need to retain the initiative because it will 
// change in our &vor anyway 
PlayAny(gList [3]. move): 
return; 

] 


// It is possible to liave more than one HandOut avadabk so 
// count the number of each kind of HandDut possibility, 
int nuni2ho * // the number of length 2 hand out possibilities 
num4ho; // the number of length 4 hand out possibilities 

num2ho = niLirE4ho = 0: 

F0R_LIST[temp. 3) 

if (temp->t¥opath->pathsize = 2) 
nuiii2ho++: 
else 

num4hQ-H-: 

num4ht> /= 2 : // were counted twice 
if fiium2ho -i- num4ho > 1] 

I // More than one hand out available so grah another square first 
if (num4ho) 

I // take the box from a length 4 2-path 
temp ^ gList[3]; 
assert(temp'>twopath}: 
while ftemp->twcipath->pathsize 1= 4) 
temp = temp->next; 

FlayAny[temp, move); 
return; 

1 

// more titan one length=2 hand outs available so play^ one 
PlayAny(gList[3]. move); 
return; 


// unsafe & gLiscI3]!“NlIIl & all 3'boxes are part of 2-lists 
// Takt- all 3’s iJiai will not ruin HandOut possibilitieii 
F0R_LlST[tEmp, 3) 

I 

// if connecting 2-path is not of length 2 or 4 then take it 

ASS ERT(t emp -> two path): 

int size = temp->twopath->pathsize; 

if (size !“ 2 size != 4} 

I 

P1ayAny[t emp. move): 
return: 

I 

// if 2-path looks like 3-2-2 2 then take it 
if (size “ 4) 

I 

pathdirection p.dxr = 0utPatlil3irection(teiiip): 
PtrToBoxReeord hox2 = 

temp->piieKt [pdlr] ->pnext [pdlrj ■>pnext[pdlr]: 
if (NuiiiberOfEdges(box2) — 2) 
t 

FlayAny(temp. move); 
return; 


I 

] 

// N(jw all 3-paths look like 3-2 or 3-2-2-3. These both arc 
// are liand out possibilities.., 

// 

if 2-path 

// 

/ / 4-path 


I “ " -> \~J~J 


// only one handout possibility 

// Nfiw see if it’s worth it, or we should just be greedy, 
if (ExpectedScoretgList[3]‘>twopath) ' 2 < 

gHaxScore - gTotalScore) 
( // It's not worth it just be greedy and don’t give handout 
PlayAnyCgList [3] ♦ move): 
return: 


if (num2ho) 

I //doaTPH 

HandOut(2. move]; 
return; 


ASSERT(numAho = i): 
//doaFPH (ickk) 

HandOut(4. move); 

I // ComputerTum 


iMakeReaLMove 

// Makes a move on the board. Returns true if a new block was formed. 

Boolean MakeRealMove(MoveRecordType move, who whoseturn) I 

//Take care of the player’s moTC 
#±fdef DRAWING 

DrawMove(GetX(move,box)t GetY(move.box)^ move^dir); 

#endif 

int oldficore = gScore[whoseturn]: 

// score of the current player before his move 
Boolean checkneeded = false; 

AddEdge(move.box, move.dir. whoseturn): 

PtrToBoxReeord box 2 - Go(move.box. move.dir): 

AddZdge(boxZ» OppositeDirectionCmove.dir). whoseturn); 
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if (gPathsConiputed) 

I 

Boolean sa]De2path = box2->twopath && 

(move*box->twopath = box2->i:wQpath) && 

NumberOfEdges(move- box) = 3: 

if (saine2path) 

box2->twopath = NULL: 

// Ste if updatir^ move, box's 2'path updates Uiis too 

UpdatePathFtomfiiiove *box) : 

// No rim.1 to update the path again if the boxes are stiU on the same 2-patli 

if (Esame2path \\ Ebox2->twopath) 

// Note that we want box2’5 2-path to mmain NULL if set above , 

// since diat will cause a new 2'patli to be created 
UpdatePatliErom{hox2): 

I 

return oldscore gScore [whoseturn]: //did score change? 

I // MakeRealMove 


CHALLENGE INTEKFACM 

// Qmverts frtjm input data types to engine data types. Modifies box,d 

void ConvertFromUotLine(MoveEecordType &move, const DotLine 

idotllne) { 

Int X = dotline*doti.coi + 1: 
iut y ^ dotline.dot1.row + 1; 

if (x > gBoacdSizeX) 

i 

“x: 

move*dir ^ right: 

I 

else If (y > gBoardSlaeX) 

f 

-y: 

move.dir = down; 

1 

else if (dotline.dot2*col > dotline,dot!*col) 
move,dir - up: 

else // (dotline dotZ.TOW > dotline.dot 1. row) 
move.dir = left: 

move,box = B0X{x, y): 

} 

// Converts from engine data types to output data t>pes, Modifies dotline 
void ConvertToDotLlne(HoveRecordType move, DotLine &dotline) 
f 

Int X = GetX(iiiove .box): 
lut y - GetY(move.box}; 
direction d “ move.dir: 

if id = right) 

d - Left: 

++x: 

] 

else If (d. = down) 

( 

//d “ up; // not strictly necessary >) 

+-fy T 

1 

dotline.dotl*col = x - 1; 
dotline.dotl.row “ y ■ 1; 
dotline.dot2 = dotline* dot 1; 
if (d == left) 

dotline. dot 2 , ro’W++: 
else //d = up 

dotline .dot2 ,col-H-: 

I 


InitDoLs 

r Pls>' begins with a call to your ItiitlXrts routine, where you are 
given the sbe of the game board (boardSlze), an indicator of who 
plays first (pla)'First), and a pointer to a CWindow (passed as a 
WindowPtr because that’s what most toolbox routines expeet). In 
that window^ you will be required to display the progress of the 
game as it proceeds. V 


void InitDots( 

short boardSize. // numbo* of diits per mw/col in board 
Boolean /* play First 7, // true if you play first, Mse of opponent plays first 

WindowFtr dotWlndow // color window where vou should draw game rcsuJLs 

) ( 

^pragma unused(dotWindov) 

gCurrentPlayer = first player; // whose turn it is to play 

gEoardSlzeX = gBoardSizeY “ boardSlze - 1; 

Initialize(): 

InltialDrawingO : 


OpponentMove 

r After your opponent lias played, ycjur OpponentMove routine 
will be called one or more times, once for each move made by 
your opponent .The move will be provided in the opponentUne 
parameter, for use in display' and in updating your data struaures. V 
r After each of your moves, and after notification of each 
opponent move, you should display the move and the updated 
game state in the dot Window. The window should also display 
the number of squares completed by each player The details 
of the display are left to you, as long as the display is correct. 7 
void OpponentMove( 

const DotLine opponentLine 

// line formed by your opponent on previous move 

) I 

MoveRecordType move: 

CouvertFroaLDotLine (move. opponentline) r 
if (1MekeRealMove(move * gCur rantPlayer) && 

gTotalScore E= gHaxScote) 
NextPlayer(gCurrentPlayer): 


PlayDots 

/* When it is your turn to move, your PlayDots routine will be 
called. Your code should select the most advantageous move and 
return it in yourljnesIOL If that move forms a square, you can 
select an additional move, store it in yourLinesf IJ, and continue 
as long as squares are formed. PlayDots should return the number 
of moves you made during your turn. V 
short r number of lines generated 7 PlayDots ( 

BotLine yourLines {] // return the lines you form here 

) i 

Boolean mad eBox; 

MoveRecordType move; 
int moves = 0: 
do [ 

ComputerTurn(move): 

madeBox = MakeRealMove(move, gCurrentPlayer): 

ConvertToDotLine(move, youtLines[moves]); 

++iDoves: 

} while [madeBox fiiSi (gTotalScore E= gMaxScore)); 

if (gTotalScore 1= gMaxScore) 

NextPlayer(gCurrentPlayer); 
return moves: 


TermDots 

/* When all of the squares have been formed, your TermDots routine 
will be called.You should deallocate aji>^ dynamically allocated 
memory and perform anj' other cleanup required. 7 
void TerinDotsO I // return any storage you allocated 

delete [] gBoxes: 

for (int 1=0: i^3; ++1) 

r 

PtrToTwoPathRecord p “ gTwoPaths[il: 
while fp) 

[ 

PtrToTwoPathRecord p2 = p->next: 
delete p: 

P = P^: 

I 

1 

] 
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CompuPius, Inc., the Apple experts reseller. 

Get complete solutions for all your storage needs whether ifs SAN, NAS, SCSI, Fibre or 
Firewire from CompuPlus, Inc. Besides Apple, otir products are also compatible with 
UNIX, Windows NT and Linux. At CompuPlus, Inc. we are all about computer hardware, 
so call us today at (800) SSO'TSTS and talk to one of our experts to find out how easy it 
is to plug into this feature packed storage solution, integrated with Apple users in mind. 




StorCase InfoStation"* 

Ready for the future when you are! 

Simply attach the field-upgradable MoStation 9-bay storage enclosure into your Apple 
G4 USB port and experience up to 1.6 TeraBytes of plug-and-piay, worry-free storage 
for RAID or JBOD applications. Get real-time updates of chassis environmentals via 
InfoStation^s on-board monitoring utility or add the optional SNMP upgrade module, 
which will be shipping in August, along with OpenView software, and check the health 
of your storage system via the internet anywhere in the world. Or, opt to be E-mailed 
or paged about any chassis environmental changes, 

As with most StorCase products, the InfoStation ^inil iflRfi 

includes an industry-leading 7-year warranty and technology 

FREE 24/7 technical support. 


A Kingswi Techjiohgy Company 







Seagate Baracuda" 

I 80 t^ hard drive 

Seagate provides the industry's leading performance disk drives. You can find them used 
in some of the most demanding applications: 
internet servers, video editing workstations, 
network file servers and enterprise servers. 


(^Seagate. 



CompuPlus Inc. 

* the system integrators 

130 McCormick Ave.. Ste. 106. Costa Mosa. CA 92626 
E-mail: sales@compuplusjric.com 

















// Scrccn.cpp 

// Copyright 2001 Jeff Malleti, M rights reserved. 

f/include <stdlo,li> 
ilfincluiie (string >h> 

ifinclude <QulckDraw*h) 

~ DRAWING CONSriNB 


/^Tpdate a player’s score on the drawing window"/ 
void Drawscore (vho w) ( 

extern int gScoreO ; 
int n: 

Rect rect: 

n = SC0RE_X[wh 

SetRect(Street* n* SCORE_Y - 11. n + 40, SC0RE_Y + 2); 
EraseRectC&rect); 


//The fuU board can’t actually fit on the window. 1 get less than 20x20 
// boxes showing in the test code window. Therefore only draw 
// the upper4eft: portion of grid if it’s that big, 

//The maximum dimensions to draw can be adjusted here if the window 

// size is increased: 

const int MAX_X_DRAU = 25; 

const int KAX_Y_DRAW = 25; 

const int B0X_WIDTH “ 15: /'pbcei distance Ix^twcen adjacent dots"/ 

const int SC0RE_TITLE_Y - 20: 

const int SC0RE_Y = 58: /"distance of scores from tap of screenV 

const int GRIC_Y = 50; 

const int SC0RE_X[2] = (40, 1301; 

const char FUYER_INITIAL[2] “ [ '1*. '2* h 
/"PLAYER_INrnAL[wJ is the initial of player w*/ 


char s[256]; 

sprintf{s. gScore[v]): 

MoveTo(u. SCORE_Y); 

Di:awText(s. 0, strlen(s)); 
j /"DrawScorcV 

void Drawinitial (int x, int y. who person) I 

if [x <= MAX_X^DRAW && y <= MAX_Y_DRAV) 

[ 

int hor. ver: 

ScreenLQc(x. y. hor, ver): 
hot += (B0X_WIDTH / 2) - 3; 


entun direction |left=0, up, right, down!; 
enura who lflrstplayer"=0. secondplayer ]: 

extern int gBoardSizeX; 
extern int gBoatdSlaeY: 


PR(yrOT\TES 

void ScreenLoc (int x. int y. inti i, int& j); 
void DravEdge (int xl, int yi. Int x2 , Int y2); 
void DrawDotsC); 
void DrawScore (who w): 

void Drawlnltial (int x, int y. who person); 
void DrawHove(lnt x, int y, direction d); 
void DrawScoreTltleiwho person); 
void InitialDrawingO ; 


DRAWING PRCX:EDITRES 

/"Given box cwrdinates x^y returns coords of top-left point of box (i.j)7 
void ScreenLoc (int x. int y, intfr 1, int& jj I 

1 - X " B0X_WIDTH; 
j - y " B0X_WrDTH + GRID_Y: 

] /"ScreenLoc*/ 

rGiveti the coordinates of two boxes xl.yl and x2, y2, this will draw tnV 
/* an edge connecting the dot in the upper left hand comer of the two boxes."/ 
void DrawEdge {int xl. int yl* Int x2. int y2) I 

int il. jl, ±2. j2; 

ScreenLoc(xl, yl, il. jl); 

ScreenLoc{s2, y2, ±2* j2); 

HoveTodl. jl): 

LineTo(12* j2); 

1 /"DrawEdge*/ 

/"Print the dots on the screen which form the playing board*/ 
void DrawDotsO [ 


ver (BOX^WIDTH / 2) +6; 

//TcxtFace(bold>; 

KoveTo(hcir. ver): 

DrawTextC&PUYER.INITlAL[person]* 0, 1): 
//TextFace(normal>; 

) 

1 /"Drawlnitiar/ 


void DrawMove(iiit x, int y. direction d) ( 

If (x <= MX_X_DRAW y <- MAX^Y^DRAW) 

I 

switch (d) I 
case left : 

DrawEdge{x. y. x, y + 1): 
break; 
case up : 

DrawEdge(x. y. x + 1. y): 
break; 

case right ; 

DrawEdge(x +i*y*x+l*y+l): 
break; 
case down : 

DrawEdge(x, y+I. x+1, y+l); 
break: 

) 

I 

1 


void DrawScoreTitie(who person) ( 


Rect rect: 

int n = SC0R£_X [person] : 

SetRect(&rect. n, SGQRE_TITLE_Y - 11. n -i 40. 

SC0RE_T1TLE_Y + 2); 

EraseRect(&rect); 


int hor, ver, i, j; 

Rect rect: 

Int maxh ^ gBoardSizeX: 
int raaxv = gBoardSizeY; 

if (maxh > MAX_X_DRAW} 
maxh = HAX_X_DRAW: 
if (maxv > MAX_YJRAW) 
aiaxv - MAX_Y_DRAW; 

++maxh: 

++maxv: 

for( hor ^ 1: hor <= maxh: horH-) 
for( ver “ 1: ver <= maxv; ver++) | 
ScreenLoc(hor, ver* i, j): 

SetRect(^rect, i, j, i+ 1, j + 1): 
PaintOvaK&rect): 

1 

I /"DrawDots"/ 


MoveTo(n, SC0RE_TITLE_¥); 

DrawText(SiPLAYER_IKITIAL[person] . 0, 1} ; 


void InitialDrawingO [ 

DrawScoreTitieCflrstplayer): 
DrawScoreTitle(secondplayer); 

int X = SC0RE_X[firstpiayer]-10; 
int y = SC0RE_TITLE_YH: 
int x2 = SC0RE_X[ second player 1+20; 
MoveToCx. y): 

LineTo(x2* y); 

MoveTaC (x+x2)/2* SCORE„TITLE_Y- 15); 
LineTo c(x+x2)/2. EC0RE_Y+15); 

DrawDotsO ; 

} 
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Not Your Average 

Wireless Access Point 





wivu'.Jandlon.com 


share your hiQn'SpeecI Internet connection 

with both wired and wireless computers while 

protecHng your data from unauthorized access. 


The NetLINE Wireless Broadband Gateway allows you to 
share a high-speed Internet connection, such as Cable or 
DSL, with multiple computers using just a single IP 
address from your ISR Support for both 802.1 lb wireless 
and standard Ethernet connections are built-in to this router 
and access point all in one. 


The built-in firewall will protect your important files by 
preventing unauthorized access via the Internet and the 
web-based configuration makes set-up a breeze. 



100% compaHhle with SkyLINE, Airporty 
and all other 802.lib wireless cards. 

For more information contact Dr Farallon 
at 1-800-613-4954 or visit us on the web at 

www.faralloii.coiiL 


mm. 




NetLINE 

Wireless Broadband 


The NetLINE Wireless 
Broadband Gateway 
connects between your 
nefivor/c and your 
Cable/DSL modem 


Broadband 

Modem 


Wireless 

Local 

Network 











NETWORK 

MANAGEMENT 


By John C. Welch 


A Network Geek in the Big Apple 


The Expo Done Gone 

Weil, the expo is over, and another week of mayhem is in tlie 
past. While the general news reports make this out to be a 
disappointing Expo, my experience was the exaa opposite. 1 found 
this to be one of the first expos where I could easily find products for 
my world. Considering my world is network management and 
administration, and of late, training, MacWorld Expo can be something 
of a disappointment for me, even when the rest of the Mac community 
is excited. In fact, I had my first indication that this was going to be a 
^most excellent’ IT MacWorld before the show had started. 

On July 12ih, Dartware released their port of net-snmp 4,2T for 
Mac OS X. This happened with very little fanfare, yet for Mac OS X, 
and especially Mac OS X server, this is of critical importance. SNMP, 
which stands for Simple Network Management Protocol is a cross- 
platform standard for managing networks. It allows for remote status 
checking, and via the trap mechanism, some ability to perform 
management actions on remote machines. Virtually every computing 
platform supports SNMP, and although it has its problems, and 
detraaors, it gets the job done, for the most pan Unfortunately, up 
until the Dartware release, there was no SNMP support in Mac OS X 
This was, in my opinion, and I tiiink I speak for many other managers 
here, a glaring omission. It meant that even on a Unix network, Mac 
OS X would require special tools, or be unable to use many of the 
standard management tools out there, such as CA Unicenter, HP 
OpenView, etc. This was a major obstruction to Mac OS X being a first 
class network diizen. 

But thanks to the folks at Dartw^, we haw a first - class SNMP 
implementation for Mac OS X. Even better, it’s an open source 
implementation. Better still, it's based on the BSD license, and not the 
GPL This last difference is important, especially to Apple. For a 
corporation, such as Apple, the GPL is a minefield. The GPL requires 
you to post any source code for any product you create that 
incorporates GPL - licensed source code. So for Apple, if they use GPL 
code in Aqua, for example, they would be required by law to post all 
the source code that relates to the parts of Aqua using GPL code. In 
this sense, the GPL is almost a kind of viial license. Now, the argument 
could be made that the FSF, (Tree Software Foundation), who owns 
tlte GPL copyright doesn't really tend to sue people over this. Bui 
legally, that isn't the point. The fact is, if the FSF did choose to take tliis 
action, then Apple would be forced to comply, or withdraw 
immediately the affected components until the GPL code could be 
removed. Considering that the head of the F5F, Richard Stallman, is 
well known for his intense dislike for Apple as a corporate entity, 
betting on his good will is not a wise choice. 


TBe BSD license, on the other hand, makes no such requirement. 
You are allowed to use the code under the license freely, and althougli 
you are encouraged to return the code of tlie results to the community, 
you don’t have to. This is a far more ‘open’ open source/free software 
license than die GPL, and for Apple, a far better one. TliLs means tiiat 
at some point, if they desired, they could incorporate net-snmp into 
Mac OS X and Mac OS X Server, and not have to worry about what 
corporate information they would be required to release. It means that 
the chances of this happening are far higher than they would otherwise 
be, and that we, as the cximmunity of Mac network managers have a 
better chance of getting a much needed improvement faster than it 
would have happened otherwise. 

The Keynote 

You cannot discuss MacWorld Expo without mentioning the 
Keynote. Much lias been made of this already, and I think tliat many 
of the opinions show signs of being made quickly, without any real 
thought. My take on it was that this was a maintenance keynote, and 
deliberately so. Some conversations 1 had seem to prove this out In all 
honesty, tliere wasn’t a lot of Wow'’ this time around. Yes, the new G4s 
are nice, and tlie new speaker system in them is nice, and people seem 
to like the new ases a lot, Faster iMacs are always good, and though 
I personally liked the Flower Power design, enough folks disagreed 
with me, so the new cases are conservative in color We never actually 
got to see the 700MHz iMacs, so there is some rcx)m there for Apple to 
introduce something radical at the high end. No new iBooks, no big 
surprise, they aren’t that old. No new Titaniums, no CD-RW options for 
them. Again, no big surprise on that score, 1 have yet to hear about a 
CI>RW mechanism that is thin enough to fit in a TiBook. The 
announcements from the '10 on X vendors were interesting enough, 
especially tlie way Adobe seems to have re-invented Publish and 
Subscribe, The only sour note was Quark, who, in spile of being 
ridiculously late with Xpress % insists on telling us that the Carbon 
version of Xpress is right on schedule. Well, in geological terms, 1 
suppose it is. Tip from a customer, if you are late on a product, don’t 
tell me how cool the next version will be. It makes you look silly, 

'Hie scandal over the pitched camera was sRIy. First of all, how 
much tliought does it take to ensure die thing is plugged in and 
working before the keynote. Secondly, Steve didn't wing, ding, or pitch 
the thing ai anyone. He tossed it to someone about fifty feet away. 
Physics tells us that to get the camera to fly fifty feet, it needs a certain 
amount of force . The person on the receiving end hobbled tlie camera 
and the batteries got dropped. That's it, no attempt by Steve to take 
someone’s head off witli it. 

The Mac OS X lOT demo was a good idea, it was necessary to 
see that we will be getting the OS that OS X Ls supposed to be. like 


John Welch <jwelch@macseoiinars.com> is a Training and Unix Specialist for Complete Mac Seminars, the premiere Mac OS training organisation. He 
has over fifteen years of experience at making computers work. His specialties are figuring out ways to make the Mac do what nobody thinks it can. 
showing people that the Mac is the superior administrative platform, and teaching them how to use it as iust that. 
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many, I would have liked a CD to have teen taped to my seat, but I 
Gin wait until September. Tlie iDVD 2 demo went on way too long, as 
did the commercials. Then again, the seats in the keynote room 
weren’t exactly comfortable for tong periods of sitting. 

From my point of view, the most telling moment was Steve 
thanking the families of Apple employees. As soon as I saw that, the 
keynote really made sense. This was Steve essentially apologizing to 
die partners and families of die people under him for the insane work 
hours they’ have been putting in. Think about that, and think about the 
2001 time line that we saw at the keynote. With the exception of the 
iMac, Apple has, in the last year, come out with a new hardware 
lineup. Even the G4 tower has a new^ motherboard design, along with 
the new’ case. Mac OS X has teen released, and had four updates, 
iMovie, AppleWorks, FileMaker Pro, FileMaker Pro Server, and itunes 
are all native. Apple lias participated in, or put on, three trade shows, 
a developer confetencx;, and sent people to MacHack, Apple has been 
killing itself, and these people need a break, A chance to go back to 
twelve hour days instead of twenty hour days. A chance to send 
people home on the weekends. A chance to get eight hours of sleep 
instead of two. I knew some of the Apple folks, and they look 
exhausted. Remember, Apple isn’t a startup. Even under the best of 
economic times, this company is not going to have a 200% increase in 
stock value. These people have salaries, they can leave Apple, and 
work elsewhere. They can also get so burnt out that they leave die 
business entirely. That would be a shame, as these are also some of 
the smartest, most oeadve, and at least for the folks I know, some of 
the nicest people I have ever met 

So, at least to me, that was what the keynote was about. Some 
new stuff, a reminder of exaaly how furiously Apple has teen 
working since January, and a chance to give Apple employees a day 
off or two, maybe even a vacation. 

The Show 

'ITie show floor and seminars were packed with people, even if 
the vendor numbers were down this time. From an II' point of view, 
Mac OS X has liad a huge impact on the show, as compared to San 
Francisco's show. The amount of products available for the new 
operating system is simply huge, and even allowing for most of it 
being pre-ielease or other forms of beta, I was more than impressed. 

On the traditional networking front, Netopia had not only dieir 
Timbuktu pre-release out for demonstmiioa but an eariy alpha of 
netOctopus, their network administration framework as well. 
Timbuktu for Mac OS X allows you to control not only other Mac OS 
X machines, but Wintel macliines, and Mac OS 9 or earlier Macs too. 
The implementation for Mac OS X is as full - featured as the other 
versions, including the AppleScript dictionary. Other features include 
live dtxJ< displays of remote .sessions, and a floating tile that replaces 
the Mac OS 9 menu extension. The tile is piittemed the same as tlie 
Mac OS X menu bar, so if you drag it to a clear spot on the menu bar, 
it kx)ks like a menu extension. Hopefully, with version 10.1 of Mac OS 
X, this can actually live in the menu bar, although I would like to see 
the menu tile become an optional convenience. The netOctopus alpha 
I saw was looking really good, and has some new features that users 
of thi.s excellent produa have wanted for a while, including the ability 
to get the machine hardware number of the Mac via tlie Apple System 
Profiler. Color information is now included, which, thanks to Apple 


identifying machines via color, is a needed informational item. The 
SNMP module was there, and hopefially, this new version will add 
support for SNMP traps, bringing netOctopus up to the level of higher 
end network management applications. For an application which is still 
the only cross-platform management program that can run on a Mac 
as both server and client, it is good to see that Netopia’s commitment 
to the produa is unwavering. 

Another company with a similar unique position in the Mac 
market is Dantz, and to show their continued drive to make 
Retrospect the test backup program on the planet, much less the 
Mac market, they announced the first OS X - native version of 
Retrospea Server, version 5-0. This is a Carbonized version of 
Retrospect Backup Server, and is more or less a port of the 4.3 Mac 
server. As such, other than some speed improvements, and the 
ability to handle Mac OS X clients properly, there are not many 
architectural improvements to the server. However, Dantz is working 
on bringing Retrospea into the Cocoa world, and working on 
bringing over the improvements they made when they created the 
new server architecture for their Windows products. 

This will allow Dantz to give Mac administratois a high end 
backup OTver that can handle larger networks, and higher end backup 
devices tetter tlian the current versions. On the client side, Dantz has 
done an excellent job with the Mac OS X and Mac OS X Server betas 
of their clients, both Cocoa front ends to background daemons. This 
split architecture, common in the Unix world has allowed for some 
pretty significant performance inaeases. My own experiences have 
shown a consistent two to three times increase in backup speed 
between the Mac OS 9 and Mac OS X clients. (On one machine, a 
G4/450, on a clean switched 100 Mb network, the backup speed went 
from 60 -90MB/min, to 120 - 230MB/min, with no other clmges than 
OS and client.) The other performance increase is that other than an 
increase in disk activity, the user doesn’t notice the backup happening, 
so they can avoid having to set the client performance slider to the low 
end of the performance scale, avoiding the slowdown in backup 
speeds that always results. Dantz is also seeking feedback on client 
support for other Unix operating systems, so if you want to see a 
specific Unix supported, let them know. 

FileMaker announced the server version of their datal:)ase 
application, a Cocoa version. Like the Retrospect client, FileMaker Pro 
Server features a faaored interface. This allows the database server 
application to run independently of the user interface on the server. 
This allows the server to run without an active login, and without the 
overhead of the user interface. While new for Mac users, this is how 
databases such as Oracle and DB2 run, and moving to this split 
architecture is critical for FileMaker to begin giving FileMaker Pro 
Server the kind of performance and capability that it needs to keep on 
growing as a database server. Another advantage to diis split 
implementation is that it makes porting FileMaker Pro Server to other 
Unix archiiectuies easier, and FileMaker lias done exactly that, by also 
announcing the release of a Red Hat Linux version of FileMaker Pro 
Server. This now allows FileMaker administiatois to run their servers 
on higher-end hardw’are, while still maintaining a Unix server 
environment, avoiding tlie issues created by introducing Windows 
servers into such an environment. 

Mac server stalwart WebSTAR is also being revamped for Mac OS 
X, even in the face of the major question of why? After all, if you get 


September 2001 • MaCTech 


A Network Geek in the Big Apple 


93 





Apache free with Mac OS X, why pay money for a third party web 
server? Well, WebSTAR is more than just a different version of httpd, 
the web daemon in Mac OS X. First off, WebSTAE has been 
completely rewritten for Mac OS X. Although 4D started to try and 
just do a Carbon port of the Mac OS 9 version of ^bSTAE, the 
complexities in the old WebSTAR code aeated an immense barrier to 
doing this. In the end, it became a better, idea to rewrite the server 
from the ground up. This allowed for several advantages. First of all, 
tlie WebSlAR server process is actually a BSD Unix application, not 
really Cocoa or Carbon. Ihis allowed 4D to avoid any overhead for 
an administrative interface witliin the server, adding speed and 
stability. The administrative interface is a Java application, allowing it 
to be run from not only Mac OS X, l>ut also from Windows, Solaris, 
or any platform witli adequate Java support. 4D was also able to add 
Altivec optimizations where appropriate, .so not only can WebSTAR 
take advantage of multiple processors, but also takes advantage of the 
vector units on tltose prcxressors. 

WebSTAR has some other differenc'es from Apache dial give it 
advantages over Apache. One of them is the secnrity mcxlel that 
WebSTAR uses. WebSTAR has its own user database, ratiier than using 
the Netinfo database in Mac OS X. While inconvenient in the sease 
that an admin has to set up users in two places, this meaas that if 
.someone is able to crack an admin password in WebSTAR, tliey do 
not automatically have die keys to the kingdom. They may be able to 
do evil things to WebSTAR, but they still have to get a different 
password to root the OS X box WebSTAR is running on, WebSTAR 
also dcx^sn’t am as root, so even if a cracker manages to get WebSTAR 
to run unauthorized code, they are not doing diis as root, limiting the 
damage they can do easily. Wel>STAli does not nin as part of inetd, 
so trying to use WebSTAR as a way to crack this root level service fails 
as well. WebS'lAR also includes support for AppleHvent CGIs, so 
WebS'fAR administrators with a li[>raiy of AppleScrijM CGIs don’t have 
to convert them to Perl, or some odier language. Finally, 4D is 
conducting an extensive line - by - line review of WebSTAR’s source 
code, so that any code- level bugs tliat could allow sectirity breaches 
can be caught, 4D is very aware of die expeditions diat WeliSTAR’s 
success in repelling crackers lias created, and are sparing no effort to 
live up to those expectations. 

Anodier application diat has long l>een the only one of its type 
on the Mac is 4-Site Fax server. Tlie only muld-line, LAN - friendly fax 
server on the Mac, 4-Site lias languished through some clianges of 
ownership, and its user base wondered when it would simply Ix.^ killed 
off. Weil, luckily, some former developers and users of 4-Site have 
iroughl it, and were showing off die OS X version. Version 5 of 4-Site 
is a Mac OS X - native server^ with some excellent new Qifiabililies, 
First off, it now supports TCP/IP^ so the former requirements die Mac 
server had for AppleTalk are gone, Alst), the new version features 
client - independent email integration, so users can send and receive 
faxes via email, without needing a fax client. This iniegiatkin has an 
added benefri in that you can set up a machine to relay emails to the 
fax server, so dial you could allow for multiple users per client, a 
lightweigiit way of taking care of die fax needs of those users who 
don’t need a full-featured fax client. Wlien using the email integration, 
faxes are received as PDF documents, so things like OCR and other 
post - processing operations are simplified. Tlie client itself is a Java 
application, and when 1 asked if this meant that any platform 
supporting Java, outside of Windows and Mac OS X could use it, the 


reply was, “I don’t see why not. We haven’t tested it, but it should 
work.” If the 4-Site client is able to achieve this level of aoss-platform 
support, this would make it one of the Leading fax servers on the 
overall market, not just the Mac market. The new server, a Carbon 
application, will be able to handle up to 16 in/ outbound lines, giving 
4-Site a serious fax handling ability^ to start with. If 4-Site is able to work 
with die major telephony hardware developers, then Mac OS X could 
easily liecome a major force in that market. 

Our final entry is Dartware LLC, and the release of a Mac OS X - 
native version of its InterMapper application. Tliis is one of die best 
network monitoring applications available on any platform and Mac 
OS X gives it die stable liase that it needs to run 24x7. InterMapper not 
only is able to use SNMP to monitor a network, but can use other 
protocols such as POP3^ IMAP, HTTP, ITTTPS, FTP, SMTP, FileMaker 
Pro Server, etc. to make sure dial not only is the machine up on the 
network, but that the services it provides to the network are 
fiinedoning as well. InterMapper takes a diflierent approach to this than 
many similar applications. Instead of a diem agent - based approach, 
which checks these services internally on the machine they mn on, or 
via a loopback mechanism, InterMapjier uses external queries, of the 
same type that a client for that service would use. So it sends out POP3^ 
FTP, SMTP queries, and waits for the respoase. This is 

impoiiant for two reasoas. First of all, especially on Unix serveis, the 
server itseR can sStill be running, even thought the services it is 
responsible for have cra.shed. So simply seeing if die box is running is 
not enough. Setx)ndly, you can have a case where die server has gone 
cieaf, and isn’t processing external requests, even though it shows the 
services as running. By checking these services as a client would, the 
status of die service can be more accurately checked. TTie SNMP 
capabilities of InterMapper are top notch as wed. Trap notifications to 
InterMapiier are supported, and InterMapper can send its own SNMP 
traps to other applk^ations, liandy if InterMapper is monitoring part of 
a huger network run by things like UP OpenView, or Tivoli. The SNMP 
monitoring not only checks uptime, run status, pracket errors, and other 
diings, [>ut is also used to create live traffic level maps, so you can look 
at an InterMapper map, and see traffic use in real time. (Hence the 
impoitana^ of Dartware’s SNMP client release. This is invaluable for a 
Network Operadons Center, (NOC). Tlie alarms and warnings in 
InterMapper are configurable to your needs, and in addition to the trap 
rejron mechanism, InterMapper can notify you of problems via email, 
jrager, and audilile alarms. 

Off die show floor, there was the custormry excellent array of 
sessions and workshops available to educate attendees on almost 
every aspect of the Mac and the Mac OS in almosi any implementation. 
While a conflict of interest prevents me from actually reviewing 
.sessions, (I gave two sessions, and assisted on a third, also giving a 
pre-show worieshop on Mac OS Xf) I think that if you are going to take 
the time to go to an Expo, attending a session or two will gready 
increase the value you gel from the Expo, 

CONOJUSION 

So, in spite of a keynote without some amazing new 
announcement, the 2001 MacWorld Expo New York was an excellent 
show for network administrators, I will not begin to claim that 1 saw 
everything, much less covered it here, but hopefijUy, the items I was 
able to cover will give you a reason or impetus to attend your fust 
expo, or to continue going. Hi 
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